manage/CONTRIBUTING.md

Contributing

Thanks for considering a contribution to Manage.

Manage is a media and server-operations dashboard built from two subprojects:

• backend/ — FastAPI (Python 3.11) REST API using a src/ layout.
• frontend/ — Vite + React + TypeScript SPA.
• archive/ — the original Streamlit prototype, preserved for reference only. Do not use it as a guide; the app is FastAPI + React now.

The authoritative contributor quick-reference is AGENTS.md. This document mirrors it for human contributors.

Setup

Backend

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

Frontend

cd frontend
npm install

Local stack (optional)

For a full local dev stack with hot reload (auth disabled):

docker compose -f docker-compose.dev.yml up --build

The dev compose deploys only the backend and frontend; Manage never deploys an observability stack. For the optional standalone observability example, see docker-compose.observability.yml and docs/observability-runbooks.md.

Development commands

Run backend checks from backend/ and frontend checks from frontend/.

# Backend: lint + tests
cd backend && ruff check . && python -m pytest

# Run the API locally (if the package is installed as above)
uvicorn media_library_viewer_api.main:app --reload --port 8000
# Otherwise, without installing: PYTHONPATH=src uvicorn media_library_viewer_api.main:app --reload --port 8000

# Focused backend tests
pytest tests/test_api.py
pytest -k <expr>

# Frontend: dev server (proxies /api to http://localhost:8000)
cd frontend && npm run dev

# Frontend: lint + typecheck/build (build runs tsc -b + vite build) + tests
npm run lint
npm run build
npm run test

Guidelines

• Keep architecture boundaries clear:
  • clients/ for external service transports (Jellyfin, Jellyseerr, SSH, local shell).
  • integrations/ for service-registry definitions (config schema, secrets, widget kinds).
  • domain/ for normalization/business logic.
  • services/ for app services, indexing, persistence, and background workers.
  • routers/ for FastAPI route handlers.
  • models/ for Pydantic request/response schemas.
• Prefer small, focused functions and explicit names.
• Preserve safe SSH behavior and shell quoting — job templates must quote all interpolated values.
• External services (Jellyfin, Grafana, Prometheus, Alertmanager, …) are configured at runtime via the service registry in the UI, not environment variables. The only observability env var is PROMETHEUS_ENABLED (Manage's own /metrics toggle).
• Avoid introducing optional fallback paths unless required.

Backend style

Backend linting/format is Ruff (line length 120, Python 3.11); config lives in backend/pyproject.toml.

Frontend style

The frontend uses shadcn/ui + Tailwind CSS v4 + lucide-react + TanStack Query + TanStack Table. Do not introduce MUI, Emotion, recharts, d3, or AG Grid — those were removed and are not coming back.

Validation before opening a merge request

Before opening a merge request, run and ensure green:

cd backend && ruff check . && python -m pytest
cd frontend && npm run lint && npm run build && npm run test

If behavior, UX, or architecture changed, also update docs/REQUIREMENTS.md.

Security / secrets

Never commit:

• .env
• private keys or API tokens
• service secrets

Service secrets are encrypted at rest with MANAGE_ENCRYPTION_KEY (required to start the backend). Use .env.example for documented placeholders only.

Pull requests

Please include:

• what changed
• why it changed
• how it was tested (commands run / tests added)