Contributing to Celery Insights

March 15, 2026 · View on GitHub

This guide covers bug reports, feature requests, local development, and the project conventions contributors are expected to follow.

Reporting Bugs

:warning: WARNING

If you have discovered a security vulnerability, please DO NOT file a public issue. Instead, please report them directly to danyi1212@users.noreply.github.com.

If you have found a bug, we would like to know. Before you file a bug report, make sure the issue can be reproduced consistently.

To report a bug, create a new GitHub issue with the bug label and include a minimal reproduction plus any steps needed to reproduce it.

When the issue depends on real task history, logs, or runtime config, also attach a redacted debug bundle v2 from Settings -> Download diagnostics. Keep secrets redacted unless someone investigating the issue explicitly asks for the unredacted bundle.

If you are not sure whether it is a bug, start with GitHub Discussions. Other users may have seen the same behavior and can help narrow it down.

Asking Questions and Requesting Features

If you have a question, idea, or feature request, start in GitHub Discussions.

For feature requests, open a GitHub issue with the enhancement label after the discussion.

Contribution Process

To contribute to the project, follow these steps:

Fork the repository.
Create a branch with a descriptive name, using prefixes like feature/ or bug/ for the branch names.
Make your changes in the branch.
Run the project checks before you open the pull request:
- For Python code: ruff, ty, and pytest
- For frontend code: Oxlint, Oxfmt, TypeScript, and Vitest
Open a pull request to the main branch.
Check the CI workflow statuses and for comments on your pull request.

Local development

Prerequisites

Python 3.14+
Bun
SurrealDB (v3.0+)
An IDE (we suggest PyCharm, but you can use your preferred IDE)

Create dev environment

Clone your fork of the Celery Insights repository.

git clone https://github.com/<your_username>/celery-insights.git

Navigate to the root folder of the repository.
```
cd celery-insights/
```
Install the Python dependencies using uv.
```
uv sync
```
Install pre-commit hooks
```
pre-commit install
```
Install the frontend dependencies using Bun.
```
bun install
```
Create .env file
```
cd server/
cp .env.example .env
```

Run the development stack

The quickest way to start all services at once is:

bun run dev:all

If you use just, the repo also includes just dev, just lint, just typecheck, and related helper recipes.

Debug bundles and snapshot replay

Use this workflow when you need to reproduce a real incident locally without reconnecting to the original broker or result backend.

Capture:

# From the running app UI:
# Settings -> Download diagnostics

Replay with the local test compose stack:

just start
just start-reload
just start-debug /absolute/path/to/debug-bundle-v2.zip

What these recipes do:

just start starts test_project/docker-compose.yml in detached mode
just start-reload rebuilds and recreates only the celery-insights service
just start-debug ... starts the test stack with DEBUG_BUNDLE_PATH set on the celery-insights service

Replay mode is offline and read-only by design. It restores the bundled task, event, and worker data into embedded SurrealDB and disables mutating settings actions.

Or run them in separate terminals:

Start SurrealDB
```
bun run dev:surreal
```
Start the Python ingester (provided PyCharm run configuration run server)
```
cd server/
python run.py
```
Start the frontend dev server (provided PyCharm run configuration dev)
```
bun dev
```
Open browser to http://localhost:3000

Note: All application settings are owned by Bun (runtime/config.ts) and passed to Python via environment variables. The Bun package root is the repository root, but the application source now lives at the repository root under src/, runtime/, and e2e/. When adding new configuration, define it in the Bun config schema first.

Code Styles

General

Write short, concise functions and classes.
Provide detailed types and variables, including generics when needed.
Do not abbreviate variable and function names.

Python

Use type annotations, including generics when required. Code should be 100% type covered.
Avoid creating undocumented dictionaries. Use dataclasses, Pydantic models, classes, named tuples, etc.
Avoid blocking the main thread. Use asyncio interfaces whenever possible, or use asyncio.to_thread for blocking code.
Always log exceptions and errors. New package loggers should be added to logging_config.py.
Test files should end with _test.py, and not start with test_?.py.

TypeScript

Use TypeScript only, avoid using vanilla JavaScript.
Provide detailed types and variables, including generics when needed.
Prefer arrow functions and one-liner expressions.

Avoid storing React state multiple times. Use useMemo for derived states. Example:

const MyComponent: React.FC<{items: string[]}> = ({items}) => {
    // Dont
    const [lengthBad, setLength] = useState(items.length)
    useEffect(() => setLength(items.length), [items])

    // Do
    const lengthGood = useMemo(() => items.length, [items])
}

Avoid unnecessary React re-renders. Performance is important.
Bun commands and tooling run from the repository root.
Keep the frontend split by responsibility:
- src/ for the browser application
- runtime/ for the Bun server/runtime layer
- e2e/ for Playwright coverage
Routes use TanStack Router with file-based routing. src/routeTree.gen.ts is auto-generated — do not edit manually.

UI Components & Styling

Use Shadcn UI components from src/components/ui/. Add new Shadcn components via bunx shadcn@latest add <component>.
Style with Tailwind CSS v4 utility classes. Theme configuration is CSS-first in src/styles.css (no tailwind.config.js).
Use cn() from @lib/utils for conditional class merging.
Use Lucide React for all icons.
Dark mode is toggled via .dark class on <html>. Use Tailwind's dark: variant for dark-mode-specific styles.

Design Guidelines

Users are likely to be technical, so provide full information and messages.
Always show task avatars instead of IDs, and type colors near task types.
Add tooltips with description and help icons where needed.
Reactions should be near interactions; avoid toasters, popups, etc.
Add placeholders for loading or empty containers.
Display error inside components and provide detailed information.

Testing

Code should be test-covered as much as possible.

Unit tests should be written close to the module they are testing, with the same module name. For example, tests for models.py should be at models_test.py in the same folder.

Unit tests (Python)

uv run pytest                              # all tests
uv run pytest server/tasks/model_test.py   # single file

Unit tests (Frontend)

Frontend unit tests use Vitest with Testing Library and happy-dom. Tests are colocated next to the module they test, suffixed .test.ts or .test.tsx (e.g., task-avatar.tsx -> task-avatar.test.tsx).

bun run test          # all tests (single run)
bun run test:watch    # watch mode

Use the custom render from src/test-utils.tsx instead of the raw Testing Library render — it wraps components with required providers.
Use factory helpers from src/test-fixtures.ts to create test data (createServerTask, createStateTask, createServerWorker).

E2E tests (Playwright)

E2E tests run against the full docker-compose stack (celery-insights + Celery workers + RabbitMQ + Redis + interactive API).

Full lifecycle (starts and stops docker-compose automatically):

bun run e2e

With the stack already running (faster iteration):

cd test_project && docker compose --profile interactive up --build -d
E2E_SKIP_COMPOSE=1 bun run e2e

Headed mode (opens a browser so you can watch the tests run):

E2E_SKIP_COMPOSE=1 bun run e2e:headed

Playwright UI mode (interactive test runner with time-travel debugging):

E2E_SKIP_COMPOSE=1 bun run e2e:ui

Tip: When iterating locally, keep the docker-compose stack running and use E2E_SKIP_COMPOSE=1 to skip the slow build step. Use --headed to see what the tests are doing, or --ui for the full Playwright inspector.