# 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`](./AGENTS.md). This document mirrors it for human contributors.

## Setup

### Backend

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

### Frontend

```bash
cd frontend
npm install
```

### Local stack (optional)

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

```bash
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/`.

```bash
# 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>
```

```bash
# 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:

```bash
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)