API Standardization, Documentation Improvements, DX Enhancements & Ar…

[Agbeleshe]

PR: API Standardization, Documentation Improvements, DX Enhancements & Architecture Records

Overview

This PR improves the Harvest Finance backend by enhancing API documentation, standardizing response structures, improving developer experience around database migrations, and introducing Architecture Decision Records (ADRs) to preserve key technical decisions.

Key Changes

1. Enhanced Swagger Documentation for Authentication Endpoints

• Added detailed @ApiOperation decorators across all authentication endpoints.
• Added comprehensive @ApiResponse definitions for success and error scenarios.
• Added @ApiBearerAuth where JWT authentication is required.
• Documented both JWT-based and Stellar-based authentication flows.
• Improved endpoint descriptions, request schemas, and response examples.

Files Updated

• backend/src/auth/auth.controller.ts

2. Database Migration Management Scripts

Added convenient npm scripts to streamline database operations:

{
  "db:migrate": "...",
  "db:rollback": "...",
  "db:reset": "...",
  "db:seed": "..."
}

These scripts wrap the TypeORM CLI configuration and eliminate the need for contributors to memorize migration commands.

Files Updated

• backend/package.json

3. Architecture Decision Records (ADRs)

Created ADR documentation structure to preserve important architectural decisions.

Added

docs/
└── adr/
    ├── 0001-use-stellar-for-escrow.md
    ├── 0002-use-nestjs-backend.md
    └── 0003-multi-chain-adapter-pattern.md

Documented:

• Why Stellar was selected for escrow infrastructure.
• Why NestJS was chosen as the backend framework.
• Why a multi-chain adapter pattern was adopted for blockchain integrations.

4. Global Response Interceptor

Implemented a NestJS ResponseInterceptor that standardizes all API responses into a consistent envelope:

{
  "data": {},
  "meta": {}
}

Benefits:

• Consistent API contract across all endpoints.
• Simplified frontend integration.
• Easier client-side error handling and typing.

Files Added

• backend/src/common/interceptors/response.interceptor.ts

Files Updated

• backend/src/main.ts

---

Example Response Format

Before:

{
  "id": 1,
  "email": "user@example.com"
}

After:

{
  "data": {
    "id": 1,
    "email": "user@example.com"
  },
  "meta": {
    "timestamp": "2026-06-03T00:00:00Z"
  }
}

---

Benefits

• Better API discoverability through Swagger.
• Improved onboarding experience for contributors.
• Consistent response handling across frontend and backend.
• Preserved architectural knowledge for future maintainers.
• Reduced developer friction when managing database migrations.

Testing

• Verified Swagger documentation renders correctly.
• Verified auth endpoints display JWT and Stellar authentication requirements.
• Tested migration scripts locally.
• Confirmed interceptor wraps successful API responses.
• Validated ADR documents are accessible and properly structured.

Related Issues

Closes #397
Closes #396
Closes #393
Closes #379

[vercel]

@Agbeleshe is attempting to deploy a commit to the vic's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@Agbeleshe Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits