mirror of https://github.com/ghostfolio/ghostfolio
Browse Source
Spec out the 0-100 weighted score that sits on top of the existing X-Ray rules: inputs, category/rule weights, and the output schema.pull/7897/head
sesha456
4 weeks ago
1 changed files with 198 additions and 0 deletions
@ -0,0 +1,198 @@ |
|||
# Portfolio Health Score — Data Model (v1 draft) |
|||
|
|||
**Author:** sesha siva sankar (member 1) |
|||
**Date:** Wed, Sep 16 |
|||
**Task:** Define Portfolio Health Score (0-100) data model: inputs, weights, output schema |
|||
|
|||
--- |
|||
|
|||
## 1. What I'm actually building |
|||
|
|||
A single number from 0 to 100 that tells the user "how healthy is your portfolio right |
|||
now," built on top of the 17 X-Ray rules I documented yesterday |
|||
([01-xray-current-logic.md](01-xray-current-logic.md)). Today's job is just the data |
|||
model — not the actual scoring code yet. I need to nail down: what goes in, how much each |
|||
thing counts, and what comes out. |
|||
|
|||
## 2. The core decision: how do we turn 17 pass/fails into one number? |
|||
|
|||
I considered two approaches: |
|||
|
|||
- **Option A — straight percentage** (what X-Ray already does): just count |
|||
`passed / active` rules. Simple, but treats "you have zero accounts" the same as "your |
|||
North America exposure is 64% instead of 65%" — one is a real problem, the other is a |
|||
rounding difference. Not good enough for a "score" people will actually act on. |
|||
- **Option B — weighted score** (what I'm going with): every rule gets a weight (how much |
|||
it matters), and the score is what % of the _total possible weight_ you actually earned. |
|||
This lets us say "fees are more important than a slightly-off regional split," which |
|||
matches how a real advisor would think about it. |
|||
|
|||
**Formula:** |
|||
|
|||
``` |
|||
score = ( sum of weights of PASSED active rules ) / ( sum of weights of ALL active rules ) × 100 |
|||
``` |
|||
|
|||
- Only _active_ rules count (a user can turn rules off in settings — same as X-Ray does |
|||
today). If a rule is off, it's excluded from both top and bottom, so the remaining |
|||
weights auto-rebalance to 100%. |
|||
- If a user has **zero active rules** (turned everything off), there's no score — return |
|||
`null` with a reason, don't show a fake 100. |
|||
|
|||
## 3. Inputs — where the raw data comes from |
|||
|
|||
Nothing new needs to be computed. Every input already exists as output from the current |
|||
`RulesService.evaluate()` call I found yesterday: |
|||
|
|||
- `key` — which rule (e.g. `AccountClusterRiskSingleAccount`) |
|||
- `name` — human label |
|||
- `isActive` — whether the user has this rule turned on |
|||
- `value` — true/false, did it pass |
|||
- `evaluation` — the human-readable message (why it passed/failed) |
|||
- `configuration` — threshold info, if the rule has one |
|||
|
|||
So the health score is a **second layer that consumes X-Ray's existing output** — it |
|||
doesn't touch the rule classes themselves. That's a nice property: rule logic and scoring |
|||
logic stay separate, so changing a threshold doesn't mean rewriting the score, and vice |
|||
versa. |
|||
|
|||
## 4. Weights — how much each category/rule matters |
|||
|
|||
I split the 100 points across the 8 categories first, then divided each category's points |
|||
across its rules. Reasoning for each category weight is a gut-check based on "how much |
|||
financial damage does failing this actually do," not a formula — this is the part most |
|||
worth a second opinion from the team. |
|||
|
|||
| Category | Weight | Why | |
|||
| ---------------------------- | ------- | ----------------------------------------------------------------------- | |
|||
| Fees | 15 | Fees compound silently over years — easy to ignore, expensive long-term | |
|||
| Currency Cluster Risk | 15 | Being 80% in one currency is a real, sudden-shock risk (FX crash) | |
|||
| Economic Market Cluster Risk | 15 | Developed vs emerging split is a core diversification signal | |
|||
| Regional Market Cluster Risk | 15 | Same idea as above, just sliced by geography instead | |
|||
| Asset Class Cluster Risk | 15 | Stocks-vs-bonds balance is the most basic risk lever there is | |
|||
| Account Cluster Risk | 10 | Matters, but is more about convenience/consolidation than solvency | |
|||
| Emergency Fund | 10 | Important for financial safety, but sits outside "the portfolio" itself | |
|||
| Liquidity (Buying Power) | 5 | Nice to have cash on hand, but least urgent of the eight | |
|||
| **Total** | **100** | | |
|||
|
|||
Within each category, I split the points evenly across that category's rules, with two |
|||
exceptions where one rule is clearly the bigger deal: |
|||
|
|||
| Category | Rule | Weight | |
|||
| ---------------------------- | ------------------------------------------- | ------ | |
|||
| Fees | Fee Ratio | 15 | |
|||
| Currency Cluster Risk | Current Investment (currency concentration) | 7.5 | |
|||
| Currency Cluster Risk | Base Currency Investment | 7.5 | |
|||
| Economic Market Cluster Risk | Developed Markets | 7.5 | |
|||
| Economic Market Cluster Risk | Emerging Markets | 7.5 | |
|||
| Regional Market Cluster Risk | Asia Pacific | 3 | |
|||
| Regional Market Cluster Risk | Emerging Markets | 3 | |
|||
| Regional Market Cluster Risk | Europe | 3 | |
|||
| Regional Market Cluster Risk | Japan | 3 | |
|||
| Regional Market Cluster Risk | North America | 3 | |
|||
| Asset Class Cluster Risk | Equity | 7.5 | |
|||
| Asset Class Cluster Risk | Fixed Income | 7.5 | |
|||
| Account Cluster Risk | Current Investment (concentration) | 5 | |
|||
| Account Cluster Risk | Single Account | 5 | |
|||
| Emergency Fund | Setup (did you set a target) | 4 | |
|||
| Emergency Fund | Coverage (does it actually cover you) | 6 | |
|||
| Liquidity | Buying Power | 5 | |
|||
|
|||
_Coverage got more weight than Setup because "you set a target but it's not actually |
|||
covered" is the state that actually matters — setup alone is just a precondition._ |
|||
|
|||
## 5. What about rules with no threshold, or that are just structural checks? |
|||
|
|||
A few rules (like `AccountClusterRiskSingleAccount` or |
|||
`CurrencyClusterRiskBaseCurrencyCurrentInvestment`) aren't tunable — they're just |
|||
yes/no structural checks with no `thresholdMax`/`thresholdMin`. That's fine for the score |
|||
— weight doesn't care whether a rule is configurable, only whether it passed. No special |
|||
handling needed there. |
|||
|
|||
## 6. Output schema |
|||
|
|||
```jsonc |
|||
{ |
|||
"portfolioHealthScore": { |
|||
"score": 78, // 0-100, or null if no active rules |
|||
"grade": "B", // optional letter grade, see note below |
|||
"calculatedAt": "2026-09-16T10:00:00.000Z", |
|||
"activeWeight": 100, // sum of weights actually counted (after excluding inactive rules) |
|||
"categories": [ |
|||
{ |
|||
"key": "fees", |
|||
"name": "Fees", |
|||
"weight": 15, |
|||
"score": 100, // this category's own 0-100 sub-score |
|||
"rules": [ |
|||
{ |
|||
"key": "FeeRatioTotalInvestmentVolume", |
|||
"name": "Fee Ratio", |
|||
"isActive": true, |
|||
"passed": true, |
|||
"weight": 15, |
|||
"message": "Your fee ratio is 0.4%, below the 1% threshold." |
|||
} |
|||
] |
|||
}, |
|||
{ |
|||
"key": "currencyClusterRisk", |
|||
"name": "Currency Cluster Risk", |
|||
"weight": 15, |
|||
"score": 50, |
|||
"rules": [ |
|||
{ |
|||
"key": "CurrencyClusterRiskCurrentInvestment", |
|||
"name": "Currency Concentration", |
|||
"isActive": true, |
|||
"passed": false, |
|||
"weight": 7.5, |
|||
"message": "58% of your portfolio is in USD, above the 50% threshold." |
|||
}, |
|||
{ |
|||
"key": "CurrencyClusterRiskBaseCurrencyCurrentInvestment", |
|||
"name": "Base Currency Investment", |
|||
"isActive": true, |
|||
"passed": true, |
|||
"weight": 7.5, |
|||
"message": "Your largest currency bucket matches your base currency." |
|||
} |
|||
] |
|||
} |
|||
// ...remaining 6 categories, same shape |
|||
] |
|||
} |
|||
} |
|||
``` |
|||
|
|||
Notes on the schema: |
|||
|
|||
- **Category score** is computed the same way as the overall score, just scoped to that |
|||
category's rules — so the UI can show "Fees: 100%, Currency Risk: 50%" without a second |
|||
calculation. |
|||
- **`activeWeight`** is there so the frontend/API consumer can tell "was this score based |
|||
on all 100 points, or did the user turn some rules off and it's really out of 85?" — |
|||
important for not misleading people. |
|||
- **Grade** (A/B/C/D/F) is optional sugar on top of the number — easy to derive |
|||
(`score >= 90 → A`, etc.) but I'm flagging it as a separate, later decision since it's a |
|||
product/UX call, not a data modeling one. |
|||
|
|||
## 7. Edge cases I need to keep in mind going forward |
|||
|
|||
- **No holdings at all**: several rules (currency, asset class, economic/regional market) |
|||
don't run today if `hasOpenHoldings` is false — same should apply here, those categories |
|||
get excluded entirely (not scored as 0), and their weight gets redistributed like any |
|||
other inactive rule. |
|||
- **New user, no accounts yet**: same idea — `accountClusterRisk` shouldn't count against |
|||
someone who just signed up. |
|||
- **User disables a rule**: already covered above — weight renormalizes. |
|||
- **Partial credit vs binary**: keeping v1 binary (pass = full weight, fail = 0) instead of |
|||
a sliding scale (e.g. "meh, only 2% over the threshold") — sliding scale is a nice |
|||
future improvement, but adds real complexity (every rule needs a "how close were you" |
|||
calculation, not just true/false), so parking that for later, not day 2 of the sprint. |
|||
|
|||
## 8. What's next |
|||
|
|||
Tomorrow's task is the concentration formula spec (single stock/sector/country/currency), |
|||
which should slot in as a new rule/category feeding into this same weighted model — it |
|||
won't change anything I designed today, just adds more rows to the table in section 4. |
|||
Loading…
Reference in new issue