Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
104 lines (73 loc) · 3.37 KB

CONTRIBUTING.md

File metadata and controls

104 lines (73 loc) · 3.37 KB
Raw

Contributing to webhook-ai-router

Thank you for your interest in contributing. This document covers everything you need to get started.

Prerequisites

  • Node.js 22+
  • pnpm 9+
  • Docker and Docker Compose (optional)
  • Anthropic API key (optional — rule-based classifier runs without one)

Local setup

git clone https://github.com/viktor-veresh-dev/webhook-ai-router.git
cd webhook-ai-router
pnpm install
cp .env.example .env
# Set your API_KEY in .env
# Optionally set ANTHROPIC_API_KEY for AI classification

pnpm dev

Running tests

pnpm test
pnpm test:watch
pnpm test:coverage

All 236 tests run without external dependencies. The Anthropic API is always mocked.

Code style

This project follows strict engineering contracts. Before submitting a PR, verify:

  • Every function does one thing and is 20 lines or fewer
  • No more than 2 levels of nesting — use early returns
  • No magic numbers or strings — all go to src/config/constants.ts
  • All inputs validated at system boundaries
  • Every external I/O wrapped in try/catch with specific error types
  • Self-explanatory names, no abbreviations
  • Boolean variables use is*, has*, can*, should* prefixes

Architecture

The project uses Clean Architecture with four layers:

  • Domain — interfaces, models, enums, error types. Zero external dependencies.
  • Application — classification, ingestion, routing, processing services. Depends only on Domain.
  • Infrastructure — classifiers, destinations, queue, rule store, middleware. Implements Domain interfaces.
  • Controllers — HTTP endpoints. Composition root.

Key design patterns: Strategy (classifiers, destinations), Factory (destination creation), Repository (rule store).

Adding a new destination

  1. Implement IDestination in src/domain/interfaces/destination.interface.ts
  2. Register it in DestinationFactory at src/infrastructure/destinations/destination-factory.ts
  3. Add a rule to data/rules.json with your new destinationType
  4. Write tests covering send() and isHealthy()

Adding a new classifier

  1. Implement IClassifier from src/domain/interfaces/classifier.interface.ts
  2. Add selection logic in ClassificationService
  3. Write tests covering all classification categories

Submitting changes

  1. Fork the repository
  2. Create a feature branch from main (git checkout -b feature/your-feature)
  3. Write your code with tests
  4. Ensure all tests pass (pnpm test)
  5. Ensure the build succeeds (pnpm build)
  6. Commit with a clear message describing what changed and why
  7. Open a pull request against main

Pull request guidelines

  • One concern per PR — don't mix features with refactors
  • Every new function must have tests covering happy path, edge cases, and at least one error path
  • Update the relevant .ctx.md context file if you change a module's interface or behavior
  • No existing tests should break
  • No existing log messages should be shortened or removed

Routing rules

Rules live in data/rules.json and reload on every request. You can test rule changes without restarting the service.

Reporting issues

Open an issue with:

  • Clear description of the problem or suggestion
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Environment details (OS, Node version)

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.