Portfolio Risk Monitor

Three request objects drive the monitor: customer preferences (including allowAutomaticAdjustments), the portfolio with its volatility, highRiskPercentage, and current versus target allocations, and a market snapshot carrying volatilityIndex and trendPercentage.

Market state comes from crossing market.volatilityIndex with market.trendPercentage under a first hit policy: volatility above 30 with a trend below -15 reads 'severe' at a 0.8 risk factor, above 25 with below -10 'high' at 0.7, and above 20 with below -5 'moderate' at 0.5. High volatility with a positive trend above 5 is only 'neutral' at 0.3, single-signal rows cover 'elevated' volatility and a 'negative' trend, and the default is 'normal' at 0.2.

The volatility cutoffs echo how practitioners read the VIX, where sustained values above 30 signal a stressed market, and the -10 to -15 trend bands sit in the range commonly described as a correction. Pairing the two signals matters because volatility alone is ambiguous: the 'neutral' row explicitly downgrades risk when prices are volatile but rising.

Exposure combines portfolio.highRiskPercentage with the upstream market read: more than 50 percent in high-risk assets during a 'severe' or 'high' market is 'critical' at a 0.9 factor, more than 40 percent in the same conditions 'high' at 0.7, and more than 30 percent whenever assessment.marketCondition != 'normal' is 'elevated' at 0.5. Calmer books fall through to 'moderate' above 20 percent or 'low' at 0.1.

Making concentration conditional on market state is the realistic part: a 45 percent allocation to risky assets is tolerable in quiet markets but becomes the main loss driver in a drawdown, which is why the same percentage maps to different levels. The specific 20/30/40/50 breakpoints are house risk-appetite settings rather than an external standard.

Realized portfolio.volatility is judged against the market backdrop: above 30 with a marketRiskFactor over 0.6 rates 'high' at a 0.8 factor, above 25 with a factor over 0.4 'elevated' at 0.6, then unconditional bands step down through 'moderate' above 20, 'low' above 15, and 'minimal' at 0.1 for everything else.

Requiring both a volatile portfolio and a risky market for the top ratings keeps the monitor from over-reacting to a strategy that is volatile by design, such as an equity-heavy long-horizon allocation. The tiered factors feed the weighted score next, so this table effectively decides how much the portfolio's own turbulence contributes to the final category.

A weighted blend produces the headline number: riskScore multiplies the market, exposure, and volatility factors by weights of 0.3, 0.4, and 0.3, giving exposure the largest say. The same node derives portfolioDrift as abs(portfolio.currentAllocation.equity - portfolio.targetAllocation.equity) and buckets riskScore into a riskCategory of 'critical', 'high', 'moderate', or 'low' at the 0.7, 0.5, and 0.3 cutpoints that the switch reads next.

Four branches resolve in order under a first hit policy: an alert when riskCategory == 'moderate' and the market is not 'normal', a rebalance when portfolioDrift > 10 or a 'high' category coincides with portfolio.lastRebalance > 90 days, mitigation when the category is 'critical' or 'high' in a 'severe' market, and a default no-action path. The ordering means a moderately risky but drifted portfolio alerts rather than rebalances, so branch sequence is part of the policy.

On the alert branch a notification payload is assembled: alertDetails carries the customer and portfolio ids, a dayjs-formatted date, the riskScore and riskCategory, and a message embedding the market assessment, with recommendedAction fixed at 'Review portfolio allocation'. The outcome block reports status 'alert_generated', which downstream systems can use to log or dispatch the notice.

Getting back to target is expressed as concrete deltas: suggestedChanges subtracts each of portfolio.currentAllocation.equity, bonds, and cash from the matching targetAllocation values, and driftPercentage carries the measured drift into the message. Returning signed adjustments per asset class means an order-management layer can act on the output directly, and the outcome status 'rebalance_suggested' keeps the action auditable.

Defensive de-risking is computed from the target book: suggestedEquity drops the equity target by 15 points, bonds rise by up to 10, and cash absorbs the remainder so the allocation still sums to 100. The automaticChanges flag only turns true when the market is 'severe', the category 'critical', and the customer has opted in via allowAutomaticAdjustments, so the system never reallocates without consent.

Quiet portfolios exit through this step, which emits an outcome of { status: 'no_action_required' } stamped with the riskScore and a timestamp from date('now'). Recording the score even when nothing happens gives the monitoring history a baseline to compare against on the next run.