Portfolio Report Documentation
This guide describes the current report fields, how their values are derived, and the data required to replace the mock portfolio source with a real client API.
Current data status: the application exposes a local mock API. Client records, content, and report facts are not fetched from an external client system. Mock facts are synthetic but deterministic for the same normalized query, local portfolio record, and seed.
Calculation Rules
Portfolio value and performance
netFlows = deposits - withdrawals.marketPerformance = capitalBase * periodReturnPct / 100.netPerformance = marketPerformance + income + fees + eventShocks.endValue = startValue + netFlows + netPerformance, with a CHF 1,000 minimum in the mock generator.netPerformancePct = netPerformance / max(startValue + netFlows * 0.5, 1) * 100.
Benchmark and allocation
- Benchmark return uses the configured annual strategy rate, scaled by months and scenario multiplier.
relativePct = netPerformancePct - benchmarkPeriodPct.- Asset allocation and position weights are derived from end-of-period holdings and end value.
- Top positions, movers, winners, and losers are sorted by market value or contribution as shown on the page.
Journey and activity
- Cashflow totals and monthly bars are aggregated from transactions.
- Best and worst months, peak value, and maximum drawdown are derived from the generated performance series.
- The waterfall starts with opening value and adds deposits, withdrawals, income, fees, and market result to closing value.
Derived insights
- Investing style is selected from cash duration, equity weight, income yield, and transaction count thresholds.
- Structure insights use concentration, bond, cash, income, and drawdown thresholds.
- Advisor questions use concentration, bond, and cash thresholds; the final question is always added.
- Risk overview is calculated from holding classifications and concentration.
Report Pages and Data Origin
| Page | Field groups | Origin |
|---|---|---|
| Cover | Client, plan, portfolio value, return, biggest move, best month, investing style | synthetic mockcalculatedstatic copy |
| Editorial | CEO and relationship manager, market articles, narrative | static profiles/contentsynthetic eventscalculated |
| Year Summary | KPIs, benchmark, winners and losers, risk overview | synthetic mockcalculatedstatic labels |
| Position Moments | Contribution moments, position tags, takeaway | synthetic analyticscalculatedstatic copy |
| Journey | Performance chart, drawdown, waterfall, market-event timeline | synthetic mockcalculatedstatic articles |
| Style Snapshot | Allocation, largest positions, style, structure insights | synthetic holdingscalculatedstatic labels |
| ESG and Risk | ESG rating, carbon figures, peer ranking, risk categories | synthetic mockcalculatedstatic copy |
| Call to Action | Advisor questions, contact, booking URL, disclaimer | calculatedstatic profiles/content |
Real Client API: Required Data
Report and client
report.portfolioId,currency,language, periodfrom/to,asOf,createdAt, scenario.client.id,client.name; address, email, and phone for profile and contact pages.portfolio.planNr, strategy, risk profile, and base currency.
Holdings and transactions
- Each holding: name, market value, weight, asset class, industry, exposure currency, geography or region.
- Each transaction: id, booking date, type, currency, amount, and instrument where available.
- Monthly cashflows or enough transactions to aggregate them.
Performance and market data
- Opening and closing values, net flows, income, fees, performance amount and percentage.
- Monthly or dated performance points, monthly returns, peak value, and maximum drawdown.
- Benchmark return and market events with month, impact, article identifier, title, excerpt, category, and URL.
Portfolio analytics and ESG
- Allocation by asset class and instrument, contribution and return per instrument, wealth bridge, and activity summary.
- Structure metrics: top position, top-three weight, cash, bond, and income-yield percentages.
- ESG portfolio rating, carbon portfolio/reference values, peer metrics, and evidence needed for risk categories.
A real adapter must normalize these inputs into the validated ReportFacts contract before report composition. PDF pages consume the composed bundle and do not depend on upstream API field names.