Advanced portfolio risk analytics engine

[bakarezainab]

PR Summary

The platform reported returns (APY history, user yield, strategy-marketplace Sharpe) but had no risk analytics layer. Users could not answer the two questions that determine whether they should move money: "How much can I lose in a bad month?" and "Is this yield actually worth the volatility?".
docs/STRATEGY_MARKETPLACE.md explicitly flagged this gap : "has not landed — there is no analytics service in src/"

What Was Delivered

1. Pure Analytics Module — src/analytics/metrics.ts
   Zero-I/O mathematical engine implementing:

Null contract enforced: every metric returns null (never 0, Infinity, or NaN) when data is insufficient, the series is flat, or the result is mathematically undefined.

2. I/O & Service Layer — src/analytics/service.ts

• Sole consumer of YieldSnapshot Prisma records; aggregates portfolio values by exact timestamp.
• 90-day retention boundary — requests beyond available history are clearly flagged (insufficientHistory: true, actualWindowDays set to honest span).
• Exposes computePortfolioRisk(), computePortfolioRiskTimeseries(), and computeStrategyRisk() — keeping all math in metrics.ts.

3. Scheduled Persistence — src/jobs/portfolioRisk.ts

• Periodic job (default: 6 h, controlled by PORTFOLIO_RISK_INTERVAL_HOURS env var) that iterates active users and upserts risk aggregates into portfolio_risk_aggregates.
• Enables efficient ORDER BY sortinoRatio, ORDER BY annualisedVolatility for leaderboards without recomputing on every request.
• Includes automatic retries and operational alerting via alertingService.
• Wired into src/index.ts startup and graceful shutdown.

4. API Surface — src/routes/analytics.ts
   Ownership enforced: userId is extracted exclusively from the verified JWT payload — no path/query-param userId is accepted.

5. Database
   New model: PortfolioRiskAggregate in prisma/schema.prisma
   New migration: prisma/migrations/20260820000000_add_portfolio_risk_aggregates/migration.sql

Key design decisions:

• Unique constraint on (userId, window) → safe upserts on every compute run.
• Indexes on sortinoRatio and annualisedVolatility for leaderboard ORDER BY.
• insufficientHistory flag stored so dashboards can exclude under-funded rows without re-querying raw snapshots.

6. New Environment Variable

PORTFOLIO_RISK_INTERVAL_HOURS=6   # default; controls scheduled job frequency

Validated at startup via src/config/env.ts

7. Tests
   All 79 tests across 7 suites pass (exit 0).
   Also fixed a pre-existing timer-leak bug in http-client.integration.test.ts where jest.useFakeTimers() was not wrapped in try/finally, causing flaky failures in parallel Jest workers.

8. OpenAPI Spec — docs/openapi.yaml

• Added complete schemas: RiskMetrics, PortfolioRiskResponse, TimeseriesResponse, RollingVolPoint, DrawdownPoint.
• Added full path definitions for GET /analytics/risk and GET /analytics/risk/timeseries with examples.
• Fixed a pre-existing structural bug: the responses reusable-component block was placed outside components:, causing swagger-cli validate to fail with Token "responses" does not exist.
• Fixed NullableDecimal schema to use OpenAPI 3.0.3-compliant nullable: true (removing the oneOf: [{type: 'null'}] construct that is only valid in 3.1).
• Added validate:spec npm script (npx swagger-cli validate docs/openapi.yaml) — spec validates clean

Files changed

prisma/schema.prisma                                            (PortfolioRiskAggregate model + User relation)
prisma/migrations/20260820000000_add_portfolio_risk_aggregates/ (new migration)
src/analytics/metrics.ts                                        (new — canonical risk engine)
src/analytics/service.ts                                        (new — I/O layer)
src/jobs/portfolioRisk.ts                                       (new — scheduled persistence)
src/routes/analytics.ts                                         (new /risk and /risk/timeseries endpoints)
src/config/env.ts                                               (PORTFOLIO_RISK_INTERVAL_HOURS config)
src/index.ts                                                    (job wiring + shutdown)
tests/unit/analytics/metrics.test.ts                            (new — 18 unit tests)
tests/unit/analytics/no-duplicate-definitions.test.ts           (new — anti-duplication guard)
tests/integration/http-client.integration.test.ts               (bugfix — timer leak)
docs/openapi.yaml                                               (new endpoints + schema fixes)
package.json                                                    (validate:spec script; removed duplicate key)

Closes #312