Skip to content

Contributing to Depictio

Thank you for your interest in contributing to Depictio! This guide outlines the process for contributing to the project and provides resources to help you get started.

Table of Contents

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.11 or higher (3.12 recommended)
  • Docker and Docker Compose
  • Git

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR-USERNAME/depictio.git
cd depictio
  1. Add the original repository as an upstream remote:
git remote add upstream https://github.com/depictio/depictio.git

Development Environment

Option 1: Docker Compose

There are two compose files depending on your goal:

Quickstart — pre-built images (no build required)

Uses images from GHCR. MinIO is bundled by default — no .env needed:

docker compose up -d

For external S3 / bring your own MinIO:

docker compose -f docker-compose/docker-compose.no-minio.yaml up -d

Development — source mounts with hot-reload

Uses docker-compose.dev.yaml which mounts the local source tree and builds the image locally:

docker compose -f docker-compose.dev.yaml up --build --detach

Services

Service URL
Frontend http://localhost:5080
Backend API http://localhost:8058
API Docs http://localhost:8058/docs
MinIO Console http://localhost:9001

The source code is mounted as a volume in the dev file for live reloading:

volumes:
  - ./depictio:/app/depictio

Option 2: DevContainer & GitHub Codespaces

For a cloud-based or containerized IDE experience, use the provided DevContainer configuration:

VS Code DevContainer:

  1. Install the Dev Containers extension
  2. Open the repository in VS Code
  3. Click "Reopen in Container" when prompted (or use Command Palette: Dev Containers: Reopen in Container)

GitHub Codespaces:

  1. Go to the Depictio repository
  2. Click the green "Code" button
  3. Select "Codespaces" tab
  4. Click "Create codespace on main"

Both options provide a pre-configured development environment with all dependencies installed.

Alternative: Local Python Setup

For contributors who prefer local development without containers:

# Install uv: https://docs.astral.sh/uv/
curl -LsSf https://astral.sh/uv/install.sh | sh

# Sync dependencies
uv sync --all-extras

# Install Playwright browsers
uv run playwright install chromium

# Install pixi: https://pixi.sh
curl -fsSL https://pixi.sh/install.sh | bash

# Install all dependencies (includes MongoDB, Redis, MinIO)
pixi install

# Start infrastructure and services
pixi run start-infra
pixi run api      # FastAPI backend
pixi run dash     # Dash frontend

python -m venv depictio-dev-venv
source depictio-dev-venv/bin/activate
pip install -e ".[dev]"
playwright install chromium

Setting up Pre-commit Hooks

uv run pre-commit install

Docker Images

The project provides multiple Dockerfile options:

Dockerfile Description
Dockerfile_depictio_uv.dockerfile Recommended - Fast builds using uv
Dockerfile_depictio_prod.dockerfile Multi-stage production build
Dockerfile_depictio.dockerfile Legacy conda/mamba-based

Environment Variables

All critical defaults are embedded directly in the compose files, so .env is optional — docker compose up -d works out of the box.

To override credentials or settings, copy .env.example to .env:

cp .env.example .env   # only 3 lines — version, MinIO user, MinIO password

For development with docker-compose.dev.yaml, the full config lives in docker-compose/.env (already populated for local dev).

Key development variables:

Variable Description
DEPICTIO_CONTEXT Set to server for API, dash for frontend
DEPICTIO_MONGODB_WIPE Set to true to reset the database on startup
DEPICTIO_LOGGING_VERBOSITY_LEVEL Set to DEBUG for detailed logs
DEPICTIO_AUTH_SINGLE_USER_MODE true by default — disables login prompt
DEPICTIO_MINIO_ROOT_USER MinIO access key (default: minio)
DEPICTIO_MINIO_ROOT_PASSWORD MinIO secret (default: minio123)

Local Python Environment (Development)

Regardless of which development option you choose, you need local Python packages for running tests, pre-commit hooks, and the CLI.

1. Main package (tests & pre-commit)

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install depictio with all dev dependencies
uv sync --all-extras

# Set up pre-commit hooks
uv run pre-commit install

2. CLI package (separate)

The CLI is a standalone package with its own pyproject.toml:

# Install depictio-cli
cd depictio/cli
uv sync

# Verify installation
uv run depictio --help

Available tools:

Tool Command Purpose
pytest uv run pytest depictio/tests/ -xvs Run tests
pre-commit uv run pre-commit run --all-files Code quality checks
ruff uv run ruff check . Linting
ty uv run ty check depictio/ Type checking
depictio CLI cd depictio/cli && uv run depictio --help CLI commands

Project Structure

depictio/
├── api/                 # FastAPI backend (port 8058)
│   ├── main.py          # Application entry point
│   └── v1/
│       ├── configs/     # Settings models and logging config
│       ├── endpoints/   # One sub-package per resource domain
│       ├── services/    # Business logic, background tasks, lifespan
│       ├── middleware/  # Analytics and request middleware
│       └── db.py        # MongoDB / Beanie setup
├── dash/                # Dash frontend (port 5080)
│   ├── pages/           # Multi-app entry points (management, viewer, editor)
│   ├── layouts/         # Shared shell, sidebar, save logic
│   └── modules/         # One sub-package per dashboard component type
├── models/              # Shared Pydantic models (API + Dash)
├── cli/                 # Standalone CLI package (own pyproject.toml)
└── tests/               # Test suites (api/, dash/, cli/)

API Endpoint Structure

Each resource domain lives in depictio/api/v1/endpoints/<domain>_endpoints/ and typically contains a subset of:

<domain>_endpoints/
├── routes.py        # FastAPI router — path operations
├── models.py        # Request / response Pydantic models
└── utils.py         # Domain-specific helpers

Dash Component Structure

Depictio uses a modular component system in depictio/dash/modules/:

Component Purpose
card_component/ Text and summary cards
figure_component/ Plotly visualizations (Plotly Express, code mode, MultiQC plots)
image_component/ Static image display from S3
interactive_component/ Filters, dropdowns, sliders
table_component/ Interactive data tables (AG Grid)
text_component/ Rich text / Markdown cards
multiqc_component/ Embedded MultiQC HTML reports

Each component typically contains a subset of:

component_name/
├── frontend.py      # Entry point — layout and top-level callbacks
├── utils.py         # Component building logic and helpers
├── design_ui.py     # Stepper / configuration UI shown in edit mode
├── models.py        # Component-specific Pydantic models
└── callbacks/       # Callback modules split by concern

Not all files are present in every component — the structure grows with complexity.

Development Workflow

  1. Create a new branch for your feature or bugfix:

    git checkout -b <issue-type>/<issue-number>-<short-description>
# Example: feature/123-add-new-component
# Example: bugfix/456-fix-data-processing

  2. Make your changes and commit them:

    git add .
git commit -m "Description of your changes"

  3. Keep your branch updated with upstream:

    git fetch upstream
git rebase upstream/main

  4. Push your branch to GitHub:

    git push origin <issue-type>/<issue-number>-<short-description>

  5. Create a pull request on GitHub.

Testing Local Changes

Running Tests

# Run all tests
pytest depictio/tests/ -xvs

# Run with parallel execution
pytest depictio/tests/ -xvs -n auto

# Run specific test file
pytest depictio/tests/api/test_endpoints.py -xvs

Code Quality Checks

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
ty check depictio/

# Run all pre-commit hooks
pre-commit run --all-files

Writing Tests

  • Place tests in the depictio/tests/ directory
  • Follow existing structure: tests/api/, tests/dash/, tests/cli/
  • Include both unit tests and integration tests

Code Style and Standards

Depictio follows these coding standards:

  • PEP 8 for Python code style
  • Type hints for all function parameters and return values
  • Docstrings for modules, classes, and functions

We use pre-commit hooks to enforce:

Tool Purpose
ruff Code formatting and linting
ty Static type checking

Frontend Guidelines

Required for all frontend contributions

All new UI components must use DMC 2.0+ (Dash Mantine Components) and support dark/light themes.

Component library priority:

  1. Primary: DMC 2.0+ components — use for all new UI
  2. Secondary: Custom HTML/CSS — only when DMC is insufficient
  3. Deprecated: Bootstrap components — maintain only, do not extend

Theme compatibility checklist:

  • Use DMC component props for theming whenever possible — DMC 2.0+ handles dark/light automatically
  • Only fall back to inline style= with CSS variables (var(--app-bg-color), var(--app-surface-color)) when DMC has no built-in prop
  • Test in both light and dark themes
  • Never hardcode colors (#ffffff, #000000)

Multi-App Architecture

Critical for Dash contributors

The Dash frontend uses three separate applications. Callbacks must be registered in the correct app(s).

App URL Pattern Purpose
Management /dashboards, /profile, /projects Dashboard listing, user settings
Viewer /dashboard/{id} Read-only dashboard viewing
Editor /dashboard/{id}/edit Dashboard editing, save operations

Common pitfall: Registering a callback only in Editor when it should also work in Viewer.

# ✅ CORRECT: Register in both apps for view+edit features
# In dashboard_viewer.py
register_my_callback(app)
# In dashboard_editor.py
register_my_callback(app)

# ❌ WRONG: Only in editor, won't work in view mode
# In dashboard_editor.py only
register_my_callback(app)

Shared stores must be defined in depictio/dash/layouts/shared_app_shell.py → create_shared_stores()

Internal Technical Documentation

Detailed architecture notes, design decisions, and implementation internals are maintained in a private repository. If you need access (e.g. for a significant contribution), reach out to the maintainers.

Documentation

Repository

Documentation is maintained in the depictio-docs repository.

Setup

  1. Fork and clone the depictio-docs repository
  2. Install dependencies:
cd depictio-docs
pip install -r requirements.txt

Writing Documentation

  • Documentation is built using MkDocs Material
  • Source files are in the docs/ directory
  • Write in Markdown format
  • Include code examples where appropriate

Building Documentation

Preview documentation locally:

cd depictio-docs
mkdocs serve

Then open http://127.0.0.1:8000 in your browser.

Issue Reporting

Bug Reports

When reporting a bug, please include:

  • A clear, descriptive title
  • Steps to reproduce the issue
  • Expected behavior
  • Actual behavior
  • Screenshots if applicable
  • Environment information (OS, browser, Python version)

Feature Requests

When requesting a feature, please include:

  • A clear, descriptive title
  • Detailed description of the proposed feature
  • Rationale for adding the feature
  • Implementation suggestions if applicable

Pull Requests

PR Guidelines

  • Keep PRs focused on a single feature or bugfix
  • Include tests for new functionality
  • Update documentation as needed
  • Reference related issues
  • Ensure all CI checks pass

PR Template

Your PR description should include:

  • What changes were made
  • Why the changes were made
  • How to test the changes
  • Any additional context or notes

Code Review Process

All submissions require review. The review process includes:

  1. Automated checks - CI/CD pipeline runs tests and linting
  2. Code review - Maintainers review the changes
  3. Feedback - Address any requested changes
  4. Approval - Final approval and merge

Areas Needing Help

We welcome contributions in these priority areas. See the Roadmap for details.

Area What's Needed Difficulty
Templates nf-core workflow dashboard templates Medium
Quarto integration Static HTML/PDF export for publications Medium
Documentation User guides, tutorials, examples Easy
Testing E2E tests, edge cases, coverage Medium
Components Markdown component, date picker Medium

Community

Communication Channels

License

By contributing to Depictio, you agree that your contributions will be licensed under the MIT License.