# Contributing Guide

ViPPET (Visual Pipeline and Platform Evaluation Tool) is an open-source project
maintained as part of the
[Intel Edge AI Libraries](https://github.com/open-edge-platform/edge-ai-libraries).
Contributions of every size are welcome, from typo fixes in the documentation
to new pipelines, backend features, and UI components.

This page is the entry point to the contributing documentation. It links to the
area-specific guides and summarizes what to expect from each.

## Where to contribute

| Area                                                        | What you can add or change                                                                       |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Backend](./contributing/backend.md)                        | FastAPI routes, managers, GStreamer/DLStreamer integration, pipeline execution and benchmarking. |
| [How to add a new pipeline](./contributing/new-pipeline.md) | Built-in pipeline YAML files under `vippet/pipelines/` and user-created pipelines via the API.   |
| [How to add a new element](./contributing/new-element.md)   | Custom `gvapython` modules and notes on element visibility in the simple/advanced views.         |

 Input for Frontend and Documentation needed
| Area | What you can add or change |
|------|----------------------------|
| [Frontend](./contributing/frontend.md) | React/TypeScript UI, pipeline editor, metrics views, Redux store, routing. |
| [Documentation](./contributing/documentation.md) | Docusaurus pages, in-product docstrings, READMEs. |


## Repository layout (quick reference)

```text
tools/visual-pipeline-and-platform-evaluation-tool/
├── vippet/             # Backend (Python 3.12, FastAPI)
│   ├── api/            # FastAPI app, routes, schemas
│   ├── managers/       # Business logic (pipeline, camera, job, metadata, ...)
│   ├── pipelines/      # Built-in GStreamer pipeline YAMLs
│   └── tests/          # pytest / unittest suites
├── ui/                 # Frontend (React 19, TypeScript, Vite)
├── video_generator/    # Synthetic test-video generator
├── onvif_discovery/    # ONVIF camera discovery agent
├── shared/             # Runtime-mounted volumes (models, videos, scripts, metadata)
├── compose*.yml        # Docker Compose files (hardware profiles)
└── Makefile            # Main build / run / lint / test targets
```

For the architecture of each layer see the
[Architecture](./architecture.md) section.

## Ground rules

A few constraints apply to every contribution, regardless of area:

- **Do not commit `.env` files or model artifacts.** `.env` is generated by
  `setup_env.sh`; models are downloaded at runtime by the `model-download`
  service.
- **Keep API schema and generated clients in sync.** Whenever you change a
  FastAPI route or a Pydantic model, regenerate the OpenAPI schema with
  `make generate_openapi` and regenerate the UI client with
  `npm run generate:api` (from `ui/`). See
  [Backend - API schema and clients](./contributing/backend.md#api-schema-and-clients)
  for details.
- **Keep changes small and focused.** Avoid unrelated refactors in the same
  PR.

## Before you open a pull request

Run the linters and tests that cover the area you touched:

```bash
make lint        # markdownlint + ruff + pyright
make fix-linter  # auto-fix ruff issues
make format      # auto-format Python with ruff
make test        # backend unit tests in Docker
```

For documentation-only changes, `markdownlint` must pass, that is enough.

## Custodians

If you are unsure who owns a given area, the relevant *Article custodian* is
listed at the bottom of each contributing page.


:::{toctree}
:hidden:

./contributing/backend
./contributing/new-pipeline
./contributing/new-element

:::