mirror of https://github.com/ghostfolio/ghostfolio
Sesha S Sankar
4 weeks ago
committed by
GitHub
GitHub
2 changed files with 331 additions and 0 deletions
@ -0,0 +1,133 @@ |
|||
# X-Ray Feature Notes — What Exists Today |
|||
|
|||
**Author:** Sesha Siva Sankar (Member 1) |
|||
**Date:** Tue, Sep 15 |
|||
**Task:** Read existing Ghostfolio X-Ray code and document the current rule-based logic |
|||
|
|||
--- |
|||
|
|||
## Why I'm writing this |
|||
|
|||
Before I can design the new Portfolio Health Score, I need to understand what X-Ray already |
|||
does. Turns out it's basically a checklist of 17 independent "rules" that each say pass/fail |
|||
about one thing (too much cash, too little diversification, high fees, etc). Below is how it |
|||
all fits together, explained the way I'd explain it to a teammate over coffee, not a spec doc. |
|||
|
|||
--- |
|||
|
|||
## 1. The basic building block: a "Rule" |
|||
|
|||
- Every check in X-Ray (e.g. "is your cash too low?", "are your fees too high?") is its own |
|||
little class. |
|||
- They all follow the same shape, because they extend one shared base class |
|||
(`apps/api/src/models/rule.ts`). |
|||
- Every rule has to answer 4 questions: |
|||
- What's your name? (`getName()`) |
|||
- What settings do you need? (`getSettings()`) |
|||
- What's the actual check logic? (`evaluate()`) |
|||
- Are you configurable, and what's your default threshold? (`getConfiguration()`) |
|||
- The output of a check is dead simple — just: |
|||
- `value`: true or false (did it pass?) |
|||
- `evaluation`: a human-readable sentence explaining why |
|||
- There's no "warning" or "medium risk" state right now. It's binary — pass or fail. That's |
|||
one of the first things that'll need to change for a 0-100 health score. |
|||
|
|||
## 2. Where the rules actually get run |
|||
|
|||
- There's a small helper (`rules.service.ts`) whose whole job is: "given a list of rule |
|||
objects, run each one and hand back the results." It doesn't decide which rules to run — |
|||
it just executes them. |
|||
- The real wiring happens in `portfolio.service.ts`, in a big function called `getReport()`. |
|||
This is where someone manually created each rule object (currency risk rule, fee rule, |
|||
emergency fund rule, etc.) and grouped them into 8 categories. |
|||
- Nothing here is dynamic or plug-and-play — if we want to add a new rule, we'd have to edit |
|||
this file directly and add it to a category by hand. Worth flagging for later. |
|||
|
|||
## 3. The 8 categories and their 17 rules |
|||
|
|||
Here's the full list, grouped the way the app groups them: |
|||
|
|||
- **Liquidity** |
|||
- *Buying Power* — checks if your uninvested cash is below a minimum threshold (default: |
|||
just checks it's not zero / not too low). Fully configurable. |
|||
|
|||
- **Emergency Fund** |
|||
- *Setup* — checks if you've even set an emergency fund target. No threshold, just |
|||
"did you set one or not." |
|||
- *Coverage* — checks if your tagged emergency-fund holdings + cash actually cover your |
|||
target. Can fail three ways: no target set, holdings alone overshoot the target |
|||
(weird case), or holdings+cash undershoot it. Only runs if you've set a target > 0. |
|||
|
|||
- **Currency Cluster Risk** (are you too concentrated in one currency?) |
|||
- *Current Investment* — fails if your single biggest currency is more than 50% of your |
|||
portfolio value (configurable %). |
|||
- *Base Currency Investment* — fails if your biggest currency bucket (by money invested) |
|||
isn't your home currency. No threshold to tune, it's just yes/no. |
|||
|
|||
- **Asset Class Cluster Risk** (stocks vs bonds balance) |
|||
- *Equity* — fails if equities are outside a 78%–82% band. |
|||
- *Fixed Income* — fails if bonds are outside an 18%–22% band. |
|||
- Interesting detail: these are *band* checks (too high OR too low both fail), not simple |
|||
ceilings like most of the others. |
|||
|
|||
- **Account Cluster Risk** |
|||
- *Current Investment* — fails if one account holds more than 50% of your total money. |
|||
- *Single Account* — fails if you only have one account at all (or zero, which is invalid). |
|||
|
|||
- **Economic Market Cluster Risk** (developed vs emerging market split) |
|||
- *Developed Markets* — band check, must be within 68%–72%. |
|||
- *Emerging Markets* — band check, must be within 28%–32%. |
|||
|
|||
- **Regional Market Cluster Risk** (geographic spread) |
|||
- Five separate rules, one per region: Asia Pacific, Emerging Markets, Europe, Japan, |
|||
North America. Each is a band check against a hardcoded "ideal" range for that region |
|||
(e.g. North America should be 65%–69% of your advanced-market exposure). |
|||
|
|||
- **Fees** |
|||
- *Fee Ratio* — fails if total fees paid are more than 1% of your total trading volume |
|||
(buys + sells combined). Configurable. |
|||
|
|||
## 4. Can users customize any of this? |
|||
|
|||
- Yes — every rule reads its settings from `user.settings.xRayRules`, so a user can turn |
|||
individual rules on/off, or override the threshold numbers, from their account settings. |
|||
- If a user hasn't set anything, it falls back to hardcoded defaults (the percentages listed |
|||
above). |
|||
|
|||
## 5. Is there already a "score"? (Important — this is basically our starting point) |
|||
|
|||
- Short answer: **not really.** There's no 0-100 number anywhere today. |
|||
- The only "aggregation" that exists is a simple count: |
|||
- How many rules are turned on (`rulesActiveCount`) |
|||
- How many of those passed (`rulesFulfilledCount`) |
|||
- The UI just shows this as a sentence like "7 out of 9 rules align with your portfolio," |
|||
with a green check if everything passed, or a warning icon if not. No weighting, no |
|||
per-category breakdown, no severity levels. |
|||
- This tells me the Health Score feature is a genuinely new layer on top — we're not |
|||
reshaping something that already exists, we're building the scoring/weighting logic |
|||
from scratch on top of these 17 pass/fail checks. |
|||
|
|||
## 6. Key files, if I (or anyone else) need to go back and look |
|||
|
|||
- `apps/api/src/models/rule.ts` — the shared base class every rule extends |
|||
- `apps/api/src/models/interfaces/rule.interface.ts` — the contract every rule follows |
|||
- `apps/api/src/models/interfaces/evaluation-result.interface.ts` — the pass/fail + message |
|||
shape |
|||
- `apps/api/src/app/portfolio/rules.service.ts` — runs whatever rules it's handed |
|||
- `apps/api/src/app/portfolio/portfolio.service.ts` — `getReport()` (around line 1272) wires |
|||
up all 17 rules into categories; `getReportStatistics()` (around line 2005) does the |
|||
simple pass-count |
|||
- `apps/api/src/models/rules/**` — the actual 17 rule implementations, one folder per |
|||
category |
|||
- `libs/common/src/lib/interfaces/x-ray-rules-settings.interface.ts` — per-user rule |
|||
settings shape |
|||
- `apps/client/src/app/pages/portfolio/x-ray/x-ray-page.component.html` — where the |
|||
"N out of M rules" summary is rendered today |
|||
|
|||
## 7. What this means for tomorrow's task |
|||
|
|||
Tomorrow I need to define the Portfolio Health Score (0-100) data model — inputs, weights, |
|||
output schema. Based on today's reading, the natural "inputs" are these 17 existing |
|||
pass/fail evaluations (or the underlying ratios they're computed from), and the main design |
|||
question is how to turn "17 independent yes/no checks across 8 categories" into one |
|||
weighted 0-100 number instead of a flat count. |
|||
@ -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