Contributing overview

This section is for developers working on the Convoy codebase: the repository map and conventions below, plus dedicated pages for testing, the specs-first workflow, CLI internals, and authoring these docs.

Repository structure

Main applications:

• apps/web — Next.js app plus the Convex backend
• apps/cli — CLI bridge and one-shot commands
• apps/docs — this documentation site

Supporting areas:

• docs/specs — internal behavior specifications
• docs/features — implementation plans and historical notes
• playground/* — experiments and prototypes
• .devcontainer — containerized development environment

The architectural split: the web app owns product UI and backend behavior, the CLI owns local runtime execution and terminal workflows, and the docs app owns public documentation. This separation decides where new code and new documentation should live.

Conventions

General:

• prefer early returns
• use named exports
• avoid any
• avoid unsafe casts from untrusted input

Repo-specific:

• use kebab-case file names outside convex/; camelCase inside convex/ (Convex module paths cannot contain hyphens)
• keep hooks near their owning domain
• update tests for backend changes
• run lint and type checks before finishing

Documentation: if a change is user-visible, update the relevant spec under docs/specs/ and the public docs page in the same change. See Specs-first workflow.

In this section

• Testing — test commands and the failing-test-first workflow for bug fixes
• Specs-first workflow — behavior specs under docs/specs/ as the implementation source of truth
• CLI architecture and lifecycle — session/thread lifecycle, claims, retries, and the chunk pipeline
• Adding a runtime — backend, frontend, and CLI work to support a new cliType
• Authoring docs — editing and extending this docs site

To run the full stack locally, start with Quickstart: run from source.