Merge branch 'main' into feat/227

Author: KayMuna

.github/workflows/backend-governance.yml

@@ -33,4 +33,13 @@ jobs:
         run: npm ci
 
       - name: Run governance checks
-        run: npm run ci:governance
+        run: npm run ci:governance
+
+      - name: Verify OpenAPI documentation
+        run: |
+          npm run generate:openapi
+          if [ -n "$(git status --porcelain openapi.json)" ]; then
+            echo "❌ openapi.json is out of date. Run 'npm run generate:openapi' locally and commit the changes."
+            git diff openapi.json
+            exit 1
+          fi

.github/workflows/e2e.yml

@@ -31,9 +31,6 @@ jobs:
       - name: Install Playwright browsers
         run: npx playwright install chromium --with-deps
 
-      - name: Build app
-        run: npm run build
-
       - name: Run E2E tests
         run: npm run test:e2e
         env:

.gitignore

@@ -12,3 +12,8 @@
 
 # Agents
 GEMINI.md
+
+.agents/
+.claude/
+skills-lock.json
+issue.md

Add error boundary to catch and display runtime errors

@@ -0,0 +1 @@
+https://www.figma.com/design/Yja14jB0ZqnCj09eG64A8E/Untitled?node-id=39-2&t=tTIInuSrNVfsd0Sn-1 #238

backend/README.md

@@ -1,115 +1,222 @@
 # YieldVault Backend API
 
-Express.js backend for the YieldVault Stellar RWA platform.
+Express.js backend server for YieldVault Stellar RWA platform with rate limiting and health monitoring.
 
 ## Features
 
-- Health and readiness endpoints
-- Rate limiting for public API routes
-- Versioned API surface under `/api/v1`
-- Replay-safe mutations via idempotency keys
-- Background job retry policy and dead-letter metrics
-- Migration safety checks in CI
-- TypeScript with Jest test coverage
+- **Health Check Endpoint** (`/health`) - Real-time service health status
+- **Readiness Endpoint** (`/ready`) - Dependency status for deployment orchestration
+- **Rate Limiting** - Per-IP and per-API-key rate limiting to prevent abuse
+- **Dependency Monitoring** - Checks for cache and Stellar RPC availability
+- **Error Handling** - Consistent JSON error responses
+- **TypeScript** - Full type safety with TypeScript
 
 ## Quick Start
 
+### Setup
+
 ```bash
+# Install dependencies
 npm install
+
+# Create environment file
 cp .env.example .env
+```
+
+### Development
+
+```bash
+# Start development server with auto-reload
 npm run dev
 ```
 
-The server starts on `http://localhost:3000`.
+The server will start on `http://localhost:3000`.
+
+### Production
+
+```bash
+# Build TypeScript
+npm run build
+
+# Start production server
+npm start
+```
 
 ## Configuration
 
+Rate limiting and other settings are configurable via environment variables:
+
 | Variable | Default | Description |
-| --- | --- | --- |
-| `PORT` | `3000` | Server port |
-| `NODE_ENV` | `development` | Runtime mode |
-| `RATE_LIMIT_WINDOW_MS` | `900000` | Global rate limit window |
-| `RATE_LIMIT_MAX_REQUESTS` | `100` | Global requests per window |
-| `API_RATE_LIMIT_WINDOW_MS` | `60000` | API rate limit window |
-| `API_RATE_LIMIT_MAX_REQUESTS` | `30` | API requests per window |
-| `IDEMPOTENCY_KEY_TTL_MS` | `86400000` | Replay window for mutation requests |
-| `STELLAR_RPC_URL` | `https://soroban-testnet.stellar.org` | Stellar RPC endpoint |
+|----------|---------|-------------|
+| `PORT` | 3000 | Server port |
+| `NODE_ENV` | development | Environment mode |
+| `RATE_LIMIT_WINDOW_MS` | 900000 | Global rate limit window (15 min) |
+| `RATE_LIMIT_MAX_REQUESTS` | 100 | Global requests per window |
+| `API_RATE_LIMIT_WINDOW_MS` | 60000 | API rate limit window (1 min) |
+| `API_RATE_LIMIT_MAX_REQUESTS` | 30 | API requests per window |
+| `STELLAR_RPC_URL` | https://soroban-testnet.stellar.org | Stellar RPC endpoint |
 
 ## API Endpoints
 
-### Health
+### Health Check
 
-```http
+```
 GET /health
+```
+
+Returns service health status with dependency checks.
+
+**Response (200 OK):**
+```json
+{
+  "status": "healthy",
+  "timestamp": "2026-03-26T10:30:00.000Z",
+  "uptime": 3600.5,
+  "environment": "development",
+  "checks": {
+    "api": "up",
+    "cache": "up",
+    "stellarRpc": "up"
+  }
+}
+```
+
+### Readiness Check
+
+```
 GET /ready
 ```
 
-### Versioned API
+Returns service readiness state. Checks all critical dependencies before reporting ready.
+
+**Response (200 OK - Ready):**
+```json
+{
+  "ready": true,
+  "timestamp": "2026-03-26T10:30:00.000Z",
+  "dependencies": {
+    "cache": true,
+    "stellarRpc": true
+  }
+}
+```
 
-```http
-GET /api/v1/vault/summary
-GET /api/v1/transactions
-GET /api/v1/portfolio/holdings
-GET /api/v1/vault/history
-POST /api/v1/vault/deposits
-GET /api/v1/ops/job-metrics
+**Response (503 Unavailable - Not Ready):**
+```json
+{
+  "ready": false,
+  "timestamp": "2026-03-26T10:30:00.000Z",
+  "dependencies": {
+    "cache": false,
+    "stellarRpc": false
+  }
+}
 ```
 
-Legacy `/api/*` routes redirect to `/api/v1/*` with `308 Permanent Redirect`.
+### Rate Limit Exceeded
 
-## Idempotent Mutations
+```
+Status: 429 Too Many Requests
+```
+
+```json
+{
+  "error": "Too many requests",
+  "status": 429,
+  "message": "Rate limit exceeded. Please try again later.",
+  "retryAfter": 1711432200000
+}
+```
+
+## Rate Limiting
 
-Mutation endpoints require `x-idempotency-key`.
+### Global Rate Limiting
 
-- Same key + same payload returns the original response.
-- Same key + different payload returns `409 Conflict`.
-- TTL is controlled by `IDEMPOTENCY_KEY_TTL_MS`.
+Applied to all requests except `/health` and `/ready`:
+- Window: 15 minutes (configurable)
+- Max: 100 requests per window (configurable)
+- Per: IP address
 
-## Background Jobs
+### API Endpoint Rate Limiting
+
+Stricter limits for API endpoints (e.g., `/api/vault/summary`):
+- Window: 1 minute (configurable)
+- Max: 30 requests per window (configurable)
+- Per: API key (from `x-api-key` header) or IP address
+
+## Testing
+
+```bash
+# Run all tests
+npm test
 
-Job execution uses explicit retry policies per job class with exponential backoff.
-Failed jobs are written to a dead-letter sink and surfaced through job metrics.
+# Run tests in watch mode
+npm test -- --watch
 
-## Migration Safety
+# Run with coverage
+npm test -- --coverage
+```
 
-The CI scanner flags:
+## Issues Addressed
 
-- irreversible schema changes such as `DROP` and `TRUNCATE`
-- long-running or locking migration patterns
-- schema changes that add indexed columns without an index declaration
+### Issue #145: Rate Limiting
+- ✅ Global rate limiting per IP
+- ✅ Per-user/API-key rate limiting
+- ✅ Configurable via environment variables
+- ✅ Clear 429 responses with retry information
+- ✅ Tests included for rate limiting behavior
 
-Rollback expectations:
+### Issue #148: Health & Readiness Endpoints
+- ✅ `/health` endpoint for service health
+- ✅ `/ready` endpoint for deployment readiness
+- ✅ Dependency health checks (cache, RPC)
+- ✅ CI smoke test setup via npm scripts
+- ✅ Consistent response formats
 
-- Prefer additive schema changes.
-- Add indexes before deploying code that depends on them.
-- Avoid destructive drops in the same deploy as a data migration.
-- Document manual rollback steps when a migration cannot be reversed automatically.
+## CI/CD Integration
 
-Run the scanner locally with:
+### Smoke Test (CI Pipeline)
 
 ```bash
-npm run check:migrations
+# Build and start server
+npm run test:smoke
+
+# The server will start in background, ready for health checks
+# Call: curl http://localhost:3000/health
+# Call: curl http://localhost:3000/ready
 ```
 
-## Testing
+### Docker Deployment
 
-```bash
-npm test
-npm run build
-npm run check:migrations
+Example Dockerfile:
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist ./dist
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3000/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"
+CMD ["npm", "start"]
 ```
 
-## CI
+## Monitoring
 
-The backend governance workflow runs:
+Headers returned in responses:
 
-- `npm run lint`
-- `npm run test`
-- `npm run build`
-- `npm run check:migrations`
+- `RateLimit-Limit` - Request limit
+- `RateLimit-Remaining` - Requests remaining
+- `RateLimit-Reset` - Reset timestamp
 
-See [`.github/workflows/backend-governance.yml`](../.github/workflows/backend-governance.yml).
+Example:
+```
+RateLimit-Limit: 100
+RateLimit-Remaining: 95
+RateLimit-Reset: 1711432200
+```
 
 ## License
 
-MIT
+MIT