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 -- no any types 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 -- run pnpm lint in any subproject before committing
• Prettier -- run pnpm format in the backend for auto-formatting

cd vezta-be && pnpm lint        # Backend ESLint
cd vezta-fe && pnpm lint        # Frontend ESLint (next lint)
cd vezta-mobile && pnpm lint    # Mobile ESLint

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/ in any subproject. This directory is fully regenerated by Kubb. To update the API client:

1. Make your backend changes (new endpoints, modified DTOs)
2. Run pnpm export:openapi in vezta-be (or rely on auto-export at startup)
3. Run pnpm generate in vezta-fe
4. Copy vezta-fe/lib/api/gen/ to vezta-mobile/lib/api/gen/

Branch Strategy

• main -- production branch, always deployable
• Feature branches -- created off main for all new work

Branch naming:

feature/copy-trade-filters
fix/order-state-transition
refactor/market-normalizer
chore/upgrade-prisma

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(mobile): reconnect WebSocket on app foreground

Pull Request Process

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

pnpm lint
pnpm test

git push -u origin feature/your-feature

Swagger Documentation

Every backend controller must be properly decorated for OpenAPI spec accuracy, since the frontend generates its entire API client 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) { ... }
}