All persistent entities, fields, types, relationships and storage layers · Updated 2026-07-24
· See also ARCHITECTURE.md
| From | To | Cardinality | Link field | Notes |
|---|---|---|---|---|
| Portfolio | Position | 1 ──── * | positions[] |
Embedded array; ISIN unique within the portfolio |
| ArbPortfolio | Position | 1 ──── * | positions[] |
Embedded array; same ISIN can appear in multiple arb portfolios |
| Client | ArbPortfolio | * ──── * | portfolio_ids[] |
Client stores array of arb portfolio IDs; no back-reference on ArbPortfolio |
| Position (ticker) | DCFParams | * ──── 0..1 | ticker |
Optional: DCF params exist only if manually saved by the user |
| ArbPortfolio | BenchConfig | 1 ──── 0..1 | benchConfig_{id} |
Stored in browser localStorage; lost on cache clear |
| Field | Type | Notes |
|---|---|---|
| PK isin | string(12) | ISIN code — unique within a given portfolio. Auto-generated as PRIV{ticker}{ts} if absent |
| name | string | Display name of the asset |
| ticker | string | Yahoo Finance ticker symbol; may be empty for funds |
| quantity | number ≥ 0 | Number of shares / units held |
| pru | number ≥ 0 | Average purchase price (Prix de Revient Unitaire) in native currency |
| currency | string(3) |
EURUSDGBP
GBpCHFHKD
JPY
GBp = pence (÷100 to get GBP)
|
| entry_date | string? | Purchase date YYYY-MM-DD; optional |
| category | enum |
StockETFFund
CashOther
|
| potentiel | number? | Analyst target upside in %; may be negative; optional |
| secteur | string | Sector name — normalized via SECTOR_CANONICAL on the server |
| pays | string(2) | ISO 3166-1 alpha-2 country code (e.g. FR, US, DE) |
| frais | number? | Transaction fees in EUR; optional |
| Field | Type | Notes |
|---|---|---|
| positions | Position[] | Ordered list of portfolio positions. Singleton file — only one main portfolio. |
| Field | Type | Notes |
|---|---|---|
| PK id | string | Generated: arb_{timestamp_ms} |
| name | string | User-defined portfolio name |
| created | string | Creation date YYYY-MM-DD |
| type | enum |
targetstrategy
simulationwatchlist
|
| description | string? | Optional free-form description |
| positions | Position[] | Embedded array of positions |
| Field | Type | Notes |
|---|---|---|
| PK id | string | Generated: client_{timestamp_ms} |
| name | string | Client full name; required |
| string | Email address; optional | |
| phone | string? | Phone number; optional |
| risk_profile | enum |
Conservative
Moderate
Aggressive
|
| FK portfolio_ids | string[] | Array of ArbPortfolio IDs associated with this client |
| notes | string? | Free-form notes; optional |
| created | string | Creation date YYYY-MM-DD |
| Field | Type | Notes |
|---|---|---|
| PK ticker | string | Yahoo Finance ticker; top-level key in the JSON object |
| current_price | number | Price at time of save (native currency) |
| shares_outstanding | number | Total shares outstanding |
| total_debt | number | Total financial debt (used in WACC D/V) |
| total_cash | number | Cash & equivalents (added to equity value) |
| wacc | number | Discount rate (decimal); overrides auto-computed WACC when present |
| terminal_growth | number | Terminal growth rate (decimal, e.g. 0.025) |
| fcf_projections | number[] | Annual FCF projections (absolute, same currency as price); triggers complete DCF mode when non-empty |
| currency | string | Currency of the ticker (EUR, USD, GBP…) |
| last_updated | string | Date of last save YYYY-MM-DD |
| Field | Type | Notes |
|---|---|---|
| rf | number | Risk-free rate for the ticker's currency (from DCF_RF_BY_CCY) |
| beta | number | Beta from Yahoo Finance quoteSummary |
| mrp | number | Market risk premium (global DCF_MRP, default 5.5%) |
| ke | number | Cost of equity: rf + β × mrp |
| kd_gross | number | Pre-tax cost of debt from Yahoo Finance |
| tax_rate | number | Effective tax rate from Yahoo Finance |
| kd_net | number | After-tax cost of debt: kd_gross × (1 − tax) |
| ev | number | Equity ratio E/V |
| dv | number | Debt ratio D/V |
| wacc | number | Final WACC clamped to [4%, 25%] |
| Field | Type | Notes |
|---|---|---|
| PK key | string | benchConfig_{portfolioId} — stored in browser localStorage |
| countryOverrides | map<ISO2, ticker> | Country code → custom index ticker override |
| sectorOverrides | map<string, ticker> | Sector name → custom ETF ticker override |
| Field | Type | Notes |
|---|---|---|
| configs | array | List of composite benchmarks |
| PK configs[].id | number | Benchmark id (referenced as bench:{id}) |
| configs[].name | string | Display name |
| configs[].components | {ticker, weight}[] | Weighted basket of index/ETF tickers |
| active_id | number? | Currently selected config id |
| Field | Type | Notes |
|---|---|---|
| PK username | string | Login name |
| password_hash | string | bcrypt hash — never store plaintext |
| role | enum |
adminuser
|
| FK client_id | string? | For role=user: scopes access to that Client's portfolios |
| Field | Type | Notes |
|---|---|---|
| data_source | enum | yahoo eodhd |
| eodhd_api_key | string | Required when data_source=eodhd |
| esg_source | enum | excel api (excel also covers esg_data.json) |
| esg_api_url / esg_api_key | string | External ESG endpoint when esg_source=api |
| openai_api_key | string | Chat assistant; env OPENAI_API_KEY overrides |
| Field | Type | Notes |
|---|---|---|
| PK ticker | string | Exact ticker key under ratings |
| esg | number | Total ESG score |
| e / s / g | number? | Pillar scores |
| nom / year | string / number | Issuer name and fiscal year |
| Field | Type | Notes |
|---|---|---|
| PK isin | string | Instrument without live market feed |
| name / currency | string | Display meta |
| history | {date, price}[] | Manual price points |
PRIV{BASE_TICKER}{timestamp}.fcf_projections is a non-empty array in dcf_params.json. Otherwise, simple mode (Yahoo Finance data only) is used.DCF_MRP, DCF_TERM, and DCF_RF_BY_CCY are global in-process variables. The arbitrage DCF scenario temporarily overrides them via try/finally — thread-safe only in the single-threaded server model.GBp to convert to GBP before FX or P&L calculation.portfolio_ids arrays of associated Clients — stale references are silently ignored on report generation.| Method | Path | Entity / Action |
|---|---|---|
| GET | /api/portfolio | Read Portfolio.positions[] |
| POST | /api/portfolio | Append Position to Portfolio.positions[] |
| PUT | /api/portfolio/{isin} | Update Position in Portfolio.positions[] |
| DEL | /api/portfolio/{isin} | Remove Position from Portfolio.positions[] |
| POST | /api/portfolio/bulk | Batch-append Positions to Portfolio |
| GET | /api/portfolio/export | Serialize Portfolio.positions[] as CSV |
| GET | /api/arb-portfolios | Read all ArbPortfolios |
| POST | /api/arb-portfolios | Create ArbPortfolio |
| PUT | /api/arb-portfolios/{id} | Update ArbPortfolio |
| DEL | /api/arb-portfolios/{id} | Delete ArbPortfolio |
| GET | /api/dcf/params?ticker= | Read DCFParams[ticker] |
| POST | /api/dcf/params | Write DCFParams[ticker] |
| GET | /api/dcf/simple?ticker= | Compute WACCDetail + DCF (no FCF projections) |
| GET | /api/dcf/complete?ticker= | Compute WACCDetail + DCF using DCFParams.fcf_projections |
| GET | /api/dcf/portfolio?portfolio_id= | Compute DCF score for each Position.ticker in portfolio |
| GET | /api/arbitrage/simulate | Read Portfolio + ArbPortfolios → compute ArbitrageResult (not persisted) |
| GET | /api/clients | Read all Clients + hydrate portfolio details |
| POST | /api/clients | Create Client |
| PUT | /api/clients/{id} | Update Client |
| DEL | /api/clients/{id} | Delete Client |
| GET | /api/clients/{id}/report | Read Client + ArbPortfolios + live FX → compute EUR-valued report |
| GET | /api/esg?isin= | Read ESG scores from in-memory Excel data |
| GET | /api/esg/portfolio | Read ESG scores for all Portfolio.positions[] |
| GET | /api/quotes?tickers= | Fetch live quotes from Yahoo Finance (cached) |
| GET | /api/var | Monte Carlo VaR + CVaR on Portfolio (cached) |
| POST | /api/bhb | BHB attribution — reads Portfolio + benchmark data |
| GET | /api/whatif | What If simulation — reads Portfolio + user params (not persisted) |
| GET | /api/cache/clear | Purge all in-memory cache entries |