Contributing

This guide covers coding conventions, the branching strategy, and the pull request process for contributing to any Vezta subproject.

Code Standards

TypeScript

TypeScript strict mode is enabled across all subprojects. Write typed code throughout -- avoid any unless absolutely unavoidable.

• Path aliases: @/* maps to src/* in the backend; @/ maps to the project root in the frontend
• Enums: Use as const objects instead of TypeScript enums (consistent with Kubb-generated types)

Linting and Formatting

• ESLint -- pnpm lint is currently broken in both subprojects (ESLint flat-config mismatch) and is continue-on-error in CI. Use the real quality gates instead: pnpm build for the backend, and pnpm exec vitest run + tsc --noEmit for the frontend.
• Prettier -- run pnpm format in the backend for auto-formatting

cd vezta-be && pnpm lint        # Backend ESLint (currently broken — flat-config mismatch)
cd vezta-fe && pnpm lint        # Frontend ESLint via next lint (also broken — flat-config mismatch)

Financial Values

Error Response Contract

All backend errors must normalize to this shape:

{
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "Field 'amount' must be a positive number"
}

The frontend depends on this contract. Use ApiException (not raw HttpException) for domain errors that need machine-readable codes.

Generated Code

Never hand-edit files in lib/api/gen/. This directory is fully regenerated by Kubb. To update the API client:

cd vezta-be && pnpm export:openapi   # 1. Export spec
cd vezta-fe && pnpm generate         # 2. Regen frontend client
# 3. Copy vezta-be/openapi.json → vezta-docs/public/openapi.json
cd vezta-docs && pnpm generate:api   # 4. Regen API reference docs

Branch Promotion

Promotion path is dev → staging → main:

• dev -- integration branch
• staging -- release candidate
• main -- production

Branch naming for feature work:

feature/copy-trade-filters
fix/order-state-transition
refactor/market-normalizer
chore/upgrade-prisma
hotfix/cors-prod-bug
release/2026-04-30

PRs target dev for normal feature work. Hotfixes can target staging or main directly.

A governance.yml (branch-promotion policy) and security.yml (CodeQL, dependency audit, secret scan) workflow live in each subproject's .github/workflows/ (the monorepo root is not itself a git repo). All CI checks must pass before merging.

Commit Messages

Use Conventional Commits:

feat: add copy trade subscription filters
fix: correct order state machine transition for partial fills
refactor: extract normalizer into standalone service
chore: upgrade Prisma to 6.x
docs: add API client generation guide
test: add E2E tests for trading endpoints

Include the scope when the change is specific to a subproject or module:

feat(trading): add TPSL support to order creation
fix(insider-signals): correct dedup TTL for vibrant mode

Pull Request Process

git checkout dev
git pull origin dev
git checkout -b feature/your-feature

git push -u origin feature/your-feature

Swagger Documentation

Every backend controller must be properly decorated for OpenAPI spec accuracy, since the frontend (and the docs site) generates from this spec:

@ApiTags('trading')
@ApiBearerAuth('access-token')
@Controller('api/v1/trading')
export class TradingController {
  @Post('orders')
  @ApiOperation({ summary: 'Place a new order' })
  @ApiResponse({ status: 201, type: OrderResponseDto })
  @ApiResponse({ status: 400, description: 'Validation error' })
  create(@Body() dto: CreateOrderDto) { ... }
}