Investment Portfolio Tracker with Tax-Loss Alerts

A personal tool for recording what you own and what you paid for it: holdings across accounts, buy and sell transactions, cost basis, current value, realized and unrealized gains, and portfolio allocation. On top of that sits a configurable tax-loss alert engine that flags candidate situations — “you sold an asset at a loss and repurchased a similar one inside the configured window” — so the user can notice situations worth reviewing. Everything is labeled as informational calculation and education, never as tax or investment advice.

>This is a software project, not a financial advisor. The calculations are informational. Tax rules vary by jurisdiction, are frequently complex, and change. The alert engine is deliberately configurable rather than encoded to one regime, and nothing in this app constitutes tax advice, investment advice, or a recommendation to buy, sell, or hold anything. Verify your situation with a qualified professional before acting.

Who Is This For?

• Retail investors who track positions in spreadsheets and want a structured, local-first view
• Freelancers and mixed-income earners who hold investments across accounts and want one place to see cost basis and lots
• Students of finance software who want to build correct money math, lot accounting, and a rule engine without real broker integrations

The Problem

Brokerages show each account in isolation, and most people hold positions across several. The result: cost basis and gains are scattered, allocation is guesswork, and tax-relevant situations — like selling at a loss and buying a similar asset back inside a disqualifying window — are noticed only at tax time, if at all. Spreadsheets solve the tracking half but not the rules half. A student-grade project can fix both with honest arithmetic and a configurable alert engine, and it does not need a brokerage API or real market data to be genuinely educational.

How It Works

1. Record Holdings and Transactions

The core is a transaction ledger: buys and sells with date, quantity, price, and fees, grouped into accounts. Holdings are derived from the ledger — never entered by hand as a separate number that can drift out of sync.

2. Compute Cost Basis and Gains

Cost basis is calculated from lots using a configurable method (FIFO and average-cost are the two to implement first; the method is a setting, not a hardcoded choice). From lots the app derives realized gains on sales and unrealized gains on remaining positions, with the math shown step by step so it can be verified by hand.

3. Track Current Value

Current value comes from a market-price source. The MVP uses manual price entry or a sample/sandbox data feed — never a live brokerage connection and never a paid market feed by default. A clean PriceSource interface means a real quote API can be plugged in later, with rate limits and terms respected.

4. Run the Configurable Tax-Loss Alert Engine

The alert engine is a set of rules you configure, because tax regimes differ:

• Wash-sale window — the number of days between a loss sale and a repurchase that should trigger a review (some jurisdictions define a window around 30 days; the setting defaults to 30 and is documented as “common convention, verify locally”).
• Repurchase detection — a “similar” asset is matched by configurable criteria (same ticker, or same asset class when the user enables it).
• Loss thresholds — only flag loss sales above a user-set dollar amount.

When a sale + repurchase falls inside the window, the engine produces an alert — an informational flag with the dates and amounts, explicitly worded as “candidate situation worth reviewing with a professional,” never as a directive. The engine has no opinion on whether harvesting is a good idea; it only notices patterns the user asked it to notice.

5. Watch and Analyze

A watchlist tracks assets the user is researching without owning them yet. Views show allocation by asset class and account, realized/unrealized performance over time, and per-lot detail.

Key Features

• Ledger-based holdings — positions always derived from transactions
• Configurable cost-basis method — FIFO or average cost, applied consistently
• Realized / unrealized gains with hand-verifiable math
• Configurable tax-loss alert engine — window, similarity, and threshold settings
• Watchlist and portfolio allocation views
• Sample data and sandbox prices for learning without real connections
• Local-first storage with export and full deletion

Functional Requirements

User Stories

• As an investor with two brokerages, I want one ledger across accounts, so that my true allocation and gains stop living in three spreadsheets.
• As a student of the rules, I want the wash-sale alert to show me exactly which sale and repurchase triggered it, so that I understand the concept rather than just receiving a warning.
• As a careful user, I want my holdings stored locally with a full export, so that I control my financial data.

MVP Scope

Allocation charts, watchlists, per-lot tax-lot viewers, CSV import, and real (sandbox) market feeds are natural second-phase additions.

Project Timeline

• Phase 1 — Ledger and money math (Week 1): Transaction model, integer-cents arithmetic, ledger-derived holdings.
• Phase 2 — Lots and gains (Weeks 2–3): FIFO and average-cost engines with known-answer tests.
• Phase 3 — Prices and value (Week 4): Price source interface, manual entry, sample data.
• Phase 4 — Alert engine (Week 5): Configurable rules, similarity matching, informational alert wording.
• Phase 5 — Views and polish (Week 6): Allocation, watchlist, export, and docs.

Testing Strategy

• Known-answer lot tests — hand-worked FIFO and average-cost examples (including partial sales across lots) must match to the cent.
• Property tests — selling everything always zeroes holdings; realized + unrealized gains reconcile to total gain; ledger integrity holds under random transaction sequences.
• Rounding tests — per-share rounding and fee handling never create or lose cents.
• Alert engine tests — sale + repurchase inside the window alerts; outside the window does not; threshold and similarity settings change behavior as configured.
• Wording test — every alert and computed figure carries the informational disclaimer (a “not advice” content check in tests).

Security and Privacy Considerations

• Financial data is sensitive. The MVP stores data locally; if a sync/cloud layer is ever added, it must be end-to-end encrypted and clearly optional. Export and full deletion are first-class.
• No credentials, ever. The app never asks for brokerage login details. Market data comes from manual entry or sandbox/sample sources; real APIs are pluggable but require the user’s own keys, stored outside the repo and never committed.
• No fabricated rules. Tax behavior is implemented as configurable, documented settings — not encoded assumptions about one jurisdiction. The UI and README state that rules vary by jurisdiction and must be verified.
• Every output is informational. The alert engine and all figures carry the “not financial or tax advice” framing in the interface itself, not just in the README.

Success Metrics

• Math correctness: lot and gains calculations reconcile to the cent across the known-answer and property test suites.
• Configurability: changing the alert window/thresholds changes behavior exactly as documented.
• Learnability: a user who has never heard of a wash-sale can explain the trigger from the alert’s own explanation.

Common Challenges

• Money math — floating point corrupts cents; integer arithmetic from the start is the difference between correct and embarrassing.
• Lot methods — average cost and FIFO diverge on partial sales; pick one default, implement both, and test each against hand-worked examples.
• Tax complexity — real regimes are riddled with exceptions; the configurable-engine design is the honest answer, and the copy must never drift into “here’s how it works in [jurisdiction]” certainty.
• Market data — live feeds bring licensing and rate-limit baggage; a sample feed keeps the MVP honest and the scope small.
• Advice creep — every feature must resist becoming a recommendation; the alert engine notices patterns and stops there.

Learning Objectives

• Build exact money arithmetic and lot-accounting engines (FIFO, average cost) with rigorous tests.
• Model a real-world rule as a configurable engine rather than a hardcoded assumption.
• Design a pluggable data-source interface and keep external integrations optional.
• Practice compliance-minded copywriting: informational framing, disclaimers, and no overreach.

Why This Idea Is Different

This is the site’s first investing project, and it deliberately does not duplicate the three finance Ideas that exist. The personal finance tracker for freelancers handles income and spending — this project handles positions, lots, and gains. The personal credit score simulator teaches credit mechanics — this one teaches lot accounting and rule engines. The subscription manager watches recurring bills — this one watches holdings. Where they all agree is on safety: educational framing, configurable assumptions, and a hard “not advice” boundary instead of authoritative-sounding claims.

What Similar Tools Exist

| Tool type | Approach | Limitation |
|———–|———-|————|
| Brokerage dashboards | Per-account positions | Fragmented across brokers; no cross-account view |
| Spreadsheet portfolios | Manual tracking | No rules engine, error-prone formulas |
| Commercial portfolio apps | Managed aggregation | Need account connections; opaque math; cost |

This project’s differentiators: a ledger whose math is fully verifiable, a transparently configurable alert engine, no broker integrations in the MVP, and local-first privacy.

Technology Stack

• TypeScript or JavaScript — ledger, lot engine, and rules
• React (web) or React Native — interface (web keeps the MVP simplest)
• SQLite or IndexedDB — local storage of the ledger and settings
• A pluggable price source — manual entry / sample feed first; a real quote API later behind the same interface
• Vitest/Jest — known-answer, property, and wording tests

Future Enhancements

• Per-lot tax-lot viewers and scenario “what-if” (sell these lots → projected realized gain)
• CSV import from broker statements and CSV export of the full ledger
• Sandbox market feeds behind the price interface
• Clearly optional, end-to-end-encrypted sync
• Additional configurable rules (e.g., dividend reinvestment tracking) — always as settings, never as advice

Related Ideas

• Personal Finance Tracker for Freelancers — the income-and-spending half of personal finance; this project covers the investing half
• Personal Credit Score Simulator — a sibling educational finance tool that explains mechanics instead of giving advice
• Subscription Manager & Cancellation Optimizer — the site’s other configurable-rules finance project

Browse more Startup Ideas · Intermediate Ideas