MediaManager-maxdorninger/Writerside/topics/developer-guide.md

Developer Guide

This section is for those who want to contribute to Media Manager or understand its internals.

Source Code directory structure

• media_manager/: Backend FastAPI application
• web/: Frontend SvelteKit application
• Writerside/: Documentation
• metadata_relay/: Metadata relay service, also FastAPI

Special Dev Configuration

Env Variables

• BASE_PATH: this sets the base path for the app (can be set for both backend and frontend)
• PUBLIC_VERSION: this sets the version variable, it is displayed in the frontend (requires rebuilding of the frontend) and in the /api/v1/health endpoint (can be set for both backend and frontend)
• FRONTEND_FILES_DIR: directory for frontend files, e.g. in Docker container it is /app/web/build (only backend)
• MEDIAMANAGER_MISC__DEVELOPMENT: If set to TRUE, enables hot reloading of FastAPI (only when using the docker container)

Contributing

• Consider opening an issue to discuss changes before starting work

Setting up the Development Environment

I use IntellijIdea with the Pycharm and Webstorm plugins to develop this, but this guide should also work with VSCode. Normally I'd recommend Intellij, but unfortunately only Intellij Ultimate has support for FastAPI and some other features.

Recommended VSCode Plugins:

• Python
• Svelte for VSCode
• and probably more, but I don't use VSCode myself, so I can't recommend anymore.

Recommended Intellij/Pycharm Plugins:

• Python
• Svelte
• Pydantic
• Ruff
• VirtualKit
• Writerside (for writing documentation)

Other recommendations

I recommend developing using Docker, i.e. you can use the provided docker-compose.dev.yaml file. This dev docker-compose file has the ./media_manager directory mounted at /app/media_manager in the container, meaning you can run the code using the container in exactly the environment it will be running in.

Additionally, to develop the frontend I use a locally installed Node.js server. So basically a hybrid approach, where the backend runs in a container and the frontend runs on Windows. To make this work, you need to make sure the cors_urls and frontend_url are set correctly in the backend's config file.

Unfortunately, a side effect of this setup is that you have to rebuild the Docker image every time when you change the python dependencies in any way or at least restart the container if you change the code. For a fast-paced development it may be more convenient to run the backend locally too, because then it supports hot reloading.

Setting up the basic development environment with Docker

• Copy the config.dev.toml file to config.toml in the ./res directory and edit it to your needs.
• Use the following command to start the development environment with Docker:

  docker compose -f docker-compose.dev.yaml up -d
  

Setting up the backend development environment

1. Clone the repository

2. cd into repo root

3. Install uv.

4. run uv --version to verify that uv is installed correctly

5. Install python if you haven't already:

   uv python install 3.13
   

6. Create a virtual environment with uv

   uv venv --python 3.13
   

7. Install dependencies:

   uv sync
   

8. run db migrations with

     uv run alembic upgrade head
   

9. run the backend with

   uv run ./media_manager/main.py --reload --port 8000
   

• format code with uvx ruff format
• lint code with uvx ruff check

Setting up the frontend development environment

1. Clone the repository
2. cd into repo root
3. cd into web directory
4. install Node.js and npm if you haven't already, I used nvm-windows:

   nvm install 24.1.0
   nvm use 24.1.0
   

   I also needed to run the following command to be able to use npm:

   Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
   

5. Install the dependencies with npm: npm install
6. Start the frontend development server: npm run dev

• format the code with npm run format
• lint the code with npm run lint

Sequence Diagrams

sequenceDiagram
    title Step-by-step: going from adding a show to importing a torrent of one of its seasons
    
    User->>TV Router: Add a show (POST /tv/shows)
    TV Router->>TV Service: Receive Show Request
    TV Service->>MetadataProviderService: Get Metadata for Show
    MetadataProviderService->>File System: Save Poster Image
    TV Service->>Database: Store show information

    User->>TV Router: Get Available Torrents for a Season (GET /tv/torrents)
    TV Router->>TV Service: Receive Request
    TV Service->>Indexer Service: Search for torrents
    TV Service->>User: Returns Public Indexer Results

    User->>TV Router: Download Torrent (POST /tv/torrents)
    TV Router->>TV Service: Receive Request
    Note over Database: This associates a season with a torrent id and the file_path_suffix
    TV Service->>Database: Saves a SeasonFile object
    TV Service->>Torrent Service: Download Torrent
    Torrent Service->>File System: Save Torrentfile
    Torrent Service->>QBittorrent: Download Torrent

    Note over Scheduler: Hourly scheduler trigger
    Scheduler->>TV Service: auto_import_all_show_torrents()
    TV Service->>Database: Get all Shows and seasons which are associated with a torrent
    TV Service->>Torrent Service: Update Torrent download statuses
    Note over TV Service: if a torrent is finished downloading it will be imported
    TV Service->>Torrent Service: get all files in the torrents directory
    Note over Torrent Service: Extracts archives, guesses mimetype (Video/Subtitle/Other)
    Note over TV Service: filters files based on some regex and renames them
    TV Service->>File System: Move/Hardlink video and subtitle files

    Note over User: User can now access the show in e.g. Jellyfin

Tech Stack

Backend

• Python
• FastAPI
• SQLAlchemy
• Pydantic and Pydantic-Settings
• Alembic

Frontend

• TypeScript
• SvelteKit
• Tailwind CSS
• shadcn-svelte
• openapi-ts
• openapi-fetch

CI/CD

• GitHub Actions