Skip to content

Entity Map

Context

This page defines the main data entities used by the project and clarifies who reads and writes each one.

Details

Core entities and ownership: - Raw market input (data/tipranks_raw.csv): source-level input used by import workflows. - Fixture datasets (data_fixtures/*.csv): controlled test data for regression and scenario validation. - Portfolio holdings (titres): reference records whose portfolio currency is derived from the ticker (TSE: => CAD, otherwise USD). an_haut and an_bas remain raw source thresholds; the legacy _cad columns are schema-compatible copies, not converted thresholds. - Daily history (historique): one record per holding and date. valeur and devise are the native display price and currency. cad_value is the persisted CAD equivalent used only by the consolidated total, portfolio chart, and consolidated performance. fx_rate_used records a rate applied to a divergent current price and supplies the latest-snapshot rate shown on the dashboard. - Holding transactions (transactions): a separate administrator ledger for purchases and sales. Each row references one holding, preserves a source ID when seeded from data/tipranks_transactions.csv, and stores shares, unit price and the application-calculated total to two decimal places using ROUND_HALF_UP. It never replaces market snapshots or changes market indicators. The first chronological transaction must be BUY; a backdated SELL before the first BUY is rejected, while a backdated BUY is allowed when it keeps the ledger chronologically valid. Deleting a BUY is rejected with a specific English message when later SELL transactions would make the remaining share balance negative. - Demo transaction session: a short-lived copy of deterministic demo transactions and temporarily removed holding tickers. Deleting a holding's last BUY requires confirmation after all SELL transactions are gone, hides that holding from the dashboard, and blocks its detail page for the operation result. The next page refresh restores the complete baseline; the state is never written to the secure database, and 30 minutes of inactivity also triggers a fallback reset. - Quota state (logs/marketstack_quota_usage.json): current quota usage and mode transitions. - FX state (logs/fx_rate_state.json): last successful USD-to-CAD rate and retrieval timestamp, reused before a new exchange-rate API call. - Issue bridge state (logs/github_issue_bridge_state.json): current state for issue automation continuity. - Issue bridge audit trail (logs/github_issue_audit.jsonl): append-only operational trace for issue events.

Entity classes: - Reference inputs: stable inputs used to run workflows. - Operational state: mutable files updated by runtime automation. - Audit evidence: append-only logs used for troubleshooting and traceability.