Feat/backend improvements

[willowgray071-cpu]

Backend Infrastructure & Documentation Improvements

Overview

This PR implements 4 critical backend features to improve error handling, configuration management, platform visibility, and API documentation.

Changes

1. AppError Utility Class with Factory Methods (#756)

• Extended AppError with code field for error categorization
• Added static factory methods: notFound(), unauthorized(), forbidden(), badRequest(), conflict(), internalError()
• Updated error middleware to include code in response
• Refactored services and controllers to use factory methods for consistency

Benefits: Cleaner error handling, consistent error responses, easier to maintain

2. Environment Variable Validation on Startup (#757)

• Created config/env.ts with Zod schema validation
• Validates all required vars: DATABASE_URL, REDIS_URL, STELLAR_RPC_URL, ORACLE_KEYPAIR, ADMIN_JWT_SECRET, FACTORY_CONTRACT_ADDRESS
• Server exits with descriptive error if validation fails
• Updated .env.example with complete documentation

Benefits: Fail-fast on misconfiguration, prevents runtime errors, clear setup instructions

3. Platform Statistics Endpoint (#759)

• Implemented MarketService::getPlatformStats() with 60-second Redis cache
• Returns: { totalMarkets, activeMarkets, totalVolume, totalBets }
• Queries: COUNT(*) WHERE status='open', SUM(total_pool), COUNT(bets)
• Mounted at GET /api/stats for home page banner

Benefits: Real-time platform metrics, cached for performance, supports home page analytics

4. OpenAPI/Swagger Documentation (#758)

• Complete OpenAPI 3.0.3 spec covering all endpoints
• Added PlatformStats schema
• Swagger UI served at /api/docs in development
• OpenAPI spec available at /openapi.yaml
• All endpoints have request/response schemas defined

Benefits: Interactive API documentation, client code generation support, API contract clarity

Testing

• All 4 commits are independent and can be reviewed separately
• Environment validation tested with missing/invalid vars
• Platform stats endpoint tested with cache behavior
• Swagger UI verified in development mode

Deployment Notes

• No breaking changes
• New dependencies: swagger-ui-express, yaml
• Swagger UI only enabled in development mode
• Environment validation runs on every startup

Commits

1. feat: implement AppError utility class with factory methods
2. feat: set up environment variable validation on startup
3. feat: implement MarketService::getPlatformStats()
4. feat: add OpenAPI/Swagger documentation

Closes #756
Closes #757
Closes #758
Closes #759