Contributing

NestFleet is open-source under AGPL-3.0. Contributions — bug fixes, features, documentation improvements, and tests — are welcome. This page covers everything you need to get a working local development environment and submit a pull request.

Fork and clone

1. Fork the repository on GitHub: github.com/nestfleet/nestfleet
2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/nestfleet.git
   cd nestfleet

3. Add the upstream remote:

   git remote add upstream https://github.com/nestfleet/nestfleet.git

Local setup

1. Install dependencies from the repo root (this installs both API and console dependencies):

   npm install
   cd console && npm install && cd ..

2. Copy the example env file and fill in the minimum vars:

   cp .env.example .env
   # Set JWT_SECRET and DATABASE_URL at minimum

3. Start a local PostgreSQL instance. The easiest way is via Docker:

   docker run -d --name nestfleet-dev   -e POSTGRES_PASSWORD=nestfleet   -e POSTGRES_USER=nestfleet   -e POSTGRES_DB=nestfleet   -p 5434:5432   pgvector/pgvector:pg16

4. Start the API (migrations run automatically on first start):

   npm run dev

5. In a second terminal, start the Next.js console:

   cd console && npm run dev

The API starts on http://localhost:3000 and the console on http://localhost:3001 by default.

Code conventions

These conventions are enforced by ESLint and are checked in CI. PRs that fail lint will not be merged.

• Layered architecture — routes call services; services call repositories. No database access from routes. No HTTP logic in services.
• Zod validation on every route — request body, query params, and path params must be validated with a Zod schema before use.
• Auth on every route — call requireAuth() on every route handler. The ESLint rule no-unprotected-route will catch violations.
• Structured logging — use the logger fromsrc/shared/logger.ts (pino). Always includerequestId, userId, and caseId (where applicable) in log fields. Never use console.log.
• No liteLLM — use provider SDKs directly:@anthropic-ai/sdk,openai,@google/generative-ai. liteLLM is a banned dependency.
• TypeScript strict mode — no any types without an explicit comment explaining why. Prefer unknown with a type guard.

TDD policy

NestFleet follows a hybrid TDD approach: write tests first for backend logic, write them alongside for frontend components. The policy for PRs:

• New API routes require both a unit test (service layer, mocked repo) and an integration test (full route → real DB). PRs without these will be asked to add them.
• New service logic must have unit tests covering the happy path and the main error cases (invalid input, not found, permission denied).
• New worker jobs require unit tests for the job handler with mocked LLM clients.
• Bug fixes must include a test that reproduces the bug and passes after the fix.

See Running Tests for how to run the test suite.

PR guidelines

• One feature or fix per PR — small PRs are reviewed faster and are easier to revert if needed
• Explain the why, not the what — the code diff shows what changed; the PR description should explain why the change is necessary and what alternatives were considered
• Update docs — if your change adds a new environment variable, config option, or user-facing feature, update the relevant documentation page. See the Architecture doc for the key files.
• Link the issue — reference the GitHub issue your PR resolves with Closes #123 in the PR description
• Keep the diff focused — avoid bundling unrelated refactors with bug fixes

Commit style

NestFleet uses Conventional Commits. Each commit message must start with a type prefix:

Example: feat: add per-product confidence threshold to triage settings