Epic: Rework the Investments page and portfolio foundations #123

Goal

Rework the complete Investments experience using the supplied desktop/mobile redesign, while keeping the user's direct cash ↔ holding workflow and making portfolio values and performance traceable to real records.

This is the parent epic for the existing Investment Page Rework milestone. Completing one child is not completion of this epic.

Current behavior and verified foundation

• Make investment transfer links reciprocal and mutations atomic #122 — Reciprocal investment-transfer links and atomic pair mutations, implemented and merged into epic/123-investment-rework through Make investment transfer links reciprocal and mutations atomic #125. Migration 017 has disposable-D1 and private-export rehearsal evidence. This is the foundation only; it has not been released to production/main.
• Source integration, calculation, UI and final validation work is integrated; Define investment accounting, return metrics, and legacy-data compatibility #126–Validate the complete investment rework and rehearse database upgrades #135 are implemented through Define investment accounting and legacy-data compatibility #136/Add explicit investment holding metadata and opening positions #137/Record direct cash-linked investment buys and sells #139/Track dated manual investment values and whole-asset ownership #140/Normalize and cache investment market inputs #141/Unify investment values, cost basis and trade previews #142/Add historical portfolio values and cash-flow-adjusted returns #143/Redesign the investment overview, allocation and holdings #144/Add holding panels and exact-cash investment trade previews #145/Validate investment rework and make shared cash writes atomic #146. Final integration review is Rebuild Investments with cash-linked trades, performance and portfolio history #147.

The current provider paths use Yahoo Finance for market search/quotes/instrument charts and current ExchangeRate-API FX. The epic branch now supports explicit ETF/stock/crypto/manual categories, conservative opening coverage and atomic cash-linked unit buys/sells. Dated manual values and whole-asset ownership are integrated through #140. Shared normalized source inputs, cache and dated ECB FX are integrated through #141. Derived cost/gain calculations and nonmutating trade previews are integrated through #142. Historical portfolio values and daily-linked range returns are integrated through #143. The overview/allocation/holdings redesign is integrated through #144. Holding details and the dedicated trade editor are integrated through #145. Final integrated validation and SQL rehearsals are complete through #146 / #135. The complete epic-to-main review is #147. The prototype's generated prices and fixed FX are visual fixtures, not financial definitions.

Desired behavior and product decisions

• Keep direct cash ↔ holding entry. Buy creates an investment buy plus a linked cash debit; Sell creates an investment sell plus a linked cash credit. A separate broker-cash account is not required. Retain existing cash and investment tables and valid standalone history; the change builds on their relationship.
• Preserve recorded facts. Units, execution price/currency, exact cash movement/currency and explicitly entered fees are distinct. Suggested market FX is not actual execution data. Unknown historical cost, quantity start dates or FX are shown as unknown, not backfilled from current prices.
• ETF / Stock / Crypto / Manual. Distinguish asset category, pricing method, holding units and fiat quote currency. Unsupported market coverage can use a manual pricing path. Discoverable holding creation reuses Accounts rather than duplicating account management.
• Manual value is not a deposit. Store dated valuations separately from acquisition/cost and cash flows. Show value history, as-of date, stale-value attention and Update value controls.
• Real combined history. Each date uses historical units × historical unit price × dated FX, plus known manual valuations. Include sold/archived holdings during their ownership periods. Missing coverage produces visible gaps or unavailable aggregates.
• Define performance first. Net invested, remaining cost basis, realized/unrealized/total gain and range/daily performance have different meanings. The next task specifies formulas, boundaries, currency handling and worked examples. Recommended app basis is moving weighted-average remaining cost; percentage range return uses a documented time-weighted method when sufficient data exists. These are portfolio tracking metrics, not tax calculations.
• Complete the design. Header/refresh/privacy/currency/Record trade; value versus net-invested chart; three summary figures; allocation by holding/type/quote currency; filters and sortable holdings with real sparklines; actionable Needs attention; desktop holding panel/mobile detail; market chart with trades/average-cost reference; manual value history; Buy/Sell editor with exact-cash and position previews.
• Reliable shared behavior. Preserve privacy, themes, locks/archive, posted/pending semantics, fractional quantities, exports, source-revision tracking, atomic refresh/session-memory snapshots and bounded market requests. API/client/MCP must agree on the supported financial facts while retaining documented view-specific exclusions and incomplete-FX policies. MCP investment writes stay outside this epic.

Automatic dividends/corporate-action ingestion, tax-lot reporting and a broker cash ledger are not required for this redesign. Unsupported historical events must be flagged so the app does not imply complete returns.

Ordered implementation roadmap

The original roadmap rows are native sub-issues in milestone Investment Page Rework, with native Priority Medium and relevant existing area labels. Follow-up bugs #148, #150 and #159 have native Priority High. Dependencies below are also native blocked-by relationships. Work can proceed independently where the dependency graph permits; UI layout can be prototyped while its final data integration waits for the required contracts.

Current review checkpoint: Original feature/validation children, decimal fix #148 and recorded-history follow-up #150 are integrated. Subsequent fixes/features #159 / MR #160, #161 / MR #162, #163 / MR #164, #165 / MR #166 and #167 / MR #168 are integrated. Main synchronization #169 / MR #170 is integrated at 6c79af600c50695552970602bfc7c3d9f21c8082; main f2b5711e803516fce225518b0c0903b8a06bffe0 is now an ancestor of the epic.

Both independent 017 migration names remain unchanged. Combined fresh/main-first/epic-first upgrade rehearsals passed on disposable October 12 export copies with original records, migration history, integrity and rollback checks preserved. Split writes share the epic's guarded decimal cash ledger. Integration CI passed, including both client runtimes and the full Worker/D1 suite. Existing local preview data was not reset. Final MR #147 remains a separate user decision; no main merge, remote migration or production deployment has occurred.

Each child includes its own observable acceptance criteria and focused tests. Regression coverage belongs with each implementation; the final validation task checks the complete integrated experience and all migrations together.

Database and migration approach

Migration 017 is the completed relationship foundation. The remaining roadmap may require additive holding metadata, per-trade execution/fee/currency fields, dated manual valuations and market/FX cache storage; exact migrations are specified by the contract and their owning child issues. Do not redesign every table in advance or rewrite an applied migration.

For each schema change, test fresh creation and upgrade on disposable D1, preserve existing ledger facts, add export coverage and assess source-revision triggers. Rehearse the complete sequence against an up-to-date local export before production rollout. The October 12 export has passed disposable rehearsals for migration 017 and the upgrade through 021; this is evidence for that snapshot only, and does not replace the final complete-epic rehearsal in #135. Keep financial data and local configs out of commits, issues and logs.

Integration workflow

• Integration branch: epic/123-investment-rework.
• Fetch its current remote tip before each child; use the child issue number in a feature/<number>-..., task/<number>-... or other applicable branch name.
• Target every child PR to the epic branch. Make investment transfer links reciprocal and mutations atomic #125 is the completed Make investment transfer links reciprocal and mutations atomic #122 foundation; Make investment transfer links reciprocal and mutations atomic #124 is superseded review history.
• Mark a child complete when its own implementation and verification are integrated into the epic; that does not imply deployment or completion of Epic: Rework the Investments page and portfolio foundations #123.
• Keep the epic open through all features and validation. Merge the entire rework into main together only when complete and the user explicitly requests the final merge. Production migrations/deployment require their own authorization.
• CI covers main and epic branch PRs/pushes. Planning these children does not start their implementation automatically.

Acceptance criteria

• Foundation Make investment transfer links reciprocal and mutations atomic #122 is integrated into the epic and verified on disposable D1, including migration 017 rehearsal.
• Feature/validation children and follow-ups through Merge main into the investment epic and verify combined migrations #169 / MR Merge main into the investment epic safely #170 are integrated into the epic.
• Desktop/mobile overview, holdings, allocation, attention, details, manual valuation and direct-cash trade flows work against real data.
• Current/history values and returns follow the documented methods, with explicit missing-data coverage and no fabricated historic prices/costs/FX.
• Trades preserve both linked records and correct cash/unit balances atomically; manual revaluation creates no cash flow.
• API/client/MCP agree on supported semantics; privacy/themes/locks/archive/exports and financial-source revisions remain correct.
• Full relevant checks, existing end-to-end UI review and all-migration disposable-export rehearsal pass for the final release review, including the latest main integration and user visual review, with sanitized evidence.
• The final epic-to-main PR is reviewable, with migration order and limitations documented; merging/release follows explicit user authorization.

References or visuals

• Milestone: https://github.com/apptrackit/finance/milestone/1
• Foundation implementation: Make investment transfer links reciprocal and mutations atomic #125
• User-supplied Investments Redesign.dc.html (section 1a desktop, 1b mobile), plus holdings-table screenshot in this Codex conversation. The file is not publicly hosted. Its sample holdings, generated prices and fixed FX are design fixtures, not production data.