Developer
8bc209b27e
Refreshes the docs that were actively misleading about the current FastAPI + React + service-registry app, and deletes one obsolete design. - CONTRIBUTING.md: full rewrite — Streamlit-era guidance replaced with the current backend (ruff/pytest, src/ layout) + frontend (npm lint/build/test) workflow, service-registry model, and shadcn/Tailwind stack. Mirrors AGENTS.md. - README.md: removed the non-existent /addons/:addonId route (Services page is current); fixed the per-machine Jellyfin wording; replaced the py_compile dev snippet with ruff + pytest / npm lint+build+test. - backend/README.md: updated the structure tree (removed deleted clients/resources.py; added routers backups/services/tasks/widgets, integrations/, models/, widgets/, workers/); dropped the "starts the collector" sentence (MonitoringPoller is decommissioned). - frontend/README.md: corrected the uvicorn module path (main:app -> media_library_viewer_api.main:app). - Deleted docs/superpowers/specs/2026-05-08-obsidian-documentation-design.md (Obsidian vault never built; stack refs MUI/D3/AG Grid all removed). Historical docs (MIGRATION_PLAN, superpowers backup-monitoring, the bannered design/runbook/context files) deferred to a later banner pass.
120 lines
3.7 KiB
Markdown
120 lines
3.7 KiB
Markdown
# 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)
|