📖 User Guide

🚀 Getting Started

Welcome to Portfolio Tracker! This is a privacy-first portfolio tracker that works entirely in your browser. All your data is stored locally on your device - nothing is sent to any server.

First-Time Setup

1. Configure API Keys (Optional but recommended):
   • Click ⚙️ Settings
   • Enter your free API keys:
     • Finnhub - For stock prices (get free at finnhub.io)
     • Metals.dev - For precious metal prices (get free at metals.dev)
   • Keys are stored locally and never shared
2. Customize Person Names:
   • In Settings, change "John" and "Maria" to your preferred names
   • Perfect for tracking individual or joint portfolios

🏠 Main Portfolio Page

This is your dashboard showing all your assets, their current values, and portfolio summary.

Quick Stats Cards

At the top, you'll see key metrics:

• Total Portfolio Value - Combined value across all assets
• Person 1 & Person 2 Values - Individual portfolio values
• Best Performer - Asset with highest 24h gain
• Worst Performer - Asset with highest 24h loss

Main Buttons

Adding Assets

1. Click Add Asset button
2. Select asset type: Stock, Crypto, Metal, or Savings
3. Enter the symbol (e.g., AAPL, BTC, GOLD) - autocomplete will help!
4. Add a friendly name (optional - auto-filled from suggestions)
5. Enter quantities for each person
6. Click Save

Managing Assets

• Edit - Click pencil icon to modify quantities or details
• Delete - Click trash icon to remove asset
• Search - Use search box to filter assets by name or symbol
• Filter - Click All, Stocks, Crypto, Metals, or Savings to filter
• Sort - Click column headers to sort by name, type, price, or value

📈 History Page

Track your portfolio's growth over time with snapshots.

Taking Snapshots

1. Go to main portfolio page
2. Click Save Snapshot
3. Your current portfolio value is recorded with timestamp

Viewing History

• Portfolio Value Chart - Line graph showing value over time
• Snapshots Table - All saved snapshots with date, value, and change
• Delete Snapshots - Click trash icon to remove individual snapshots

📊 Charts Page

Visualize your portfolio with interactive charts.

Available Charts

• Asset Allocation Pie Chart - See percentage breakdown of your portfolio by asset
• Person Comparison Bar Chart - Compare Person 1 vs Person 2 by asset type
• Portfolio Breakdown - Total value by asset type
• Top 10 Performers - Best performing assets (24h % change)
• Bottom 10 Performers - Worst performing assets (24h % change)

🔄 Compare Page

Side-by-side comparison of Person 1 and Person 2 portfolios.

What You'll See

• Individual Portfolio Values - Total value for each person
• Asset-by-Asset Comparison - How much each person owns of each asset
• Percentage Ownership - Who owns more of each asset
• Value Breakdown - Dollar value of each person's holdings

📰 News Page

Stay updated with the latest news for your holdings.

Requirements

• Finnhub API key configured in Settings
• Stock symbols in your portfolio

Features

• Latest news articles for your stock holdings
• Filter news by specific stock symbol
• Click headlines to read full articles

📥 Import CSV Page

Bulk import assets from CSV files.

Supported Formats

• M1 Finance Export - Direct import from M1 Finance CSV
• Custom CSV - Create your own with columns: Symbol, Name, Type, Person1_Qty, Person2_Qty

How to Import

1. Select import type: M1 Finance or Custom CSV
2. Click Choose File and select your CSV
3. Review the preview
4. Map Person 1 and Person 2 names to CSV columns (for M1 Finance)
5. Click Import Assets

💾 Backup & Restore

Exporting Your Portfolio

1. Click Export on main page
2. A JSON file will download: portfolio_backup.json
3. This includes:
   • All your assets
   • Historical snapshots
   • Settings (names, API keys)

Importing a Backup

1. Click Import on main page
2. Select your portfolio_backup.json file
3. Your portfolio will be restored completely

🔒 Privacy & Security

Your Data is Safe

• 100% Local - All data stored in your browser's localStorage
• No Server - No backend database, no data collection
• No Tracking - Your portfolio never leaves your device
• API Keys Protected - Stored locally, never in source code or GitHub

Data Storage

• Data is stored in browser localStorage
• Clearing browser data will delete your portfolio
• Regular exports recommended as backups
• Each browser stores data separately

🛠️ Troubleshooting

Prices Not Updating?

• Check that API keys are configured in Settings
• Wait 60 seconds between refresh attempts (cache limitation)
• Verify API keys are valid and not expired
• Check browser console for error messages (F12)

Asset Not Found?

• Stocks - Use correct ticker symbol (e.g., AAPL not Apple)
• Crypto - Use CoinGecko IDs (bitcoin, ethereum, cardano)
• Metals - Use uppercase codes (GOLD, SILVER, PLATINUM, PALLADIUM)

Data Lost?

• Check if you cleared browser data/cache
• Verify you're using the same browser and profile
• Restore from your last JSON export

Import Failed?

• Ensure JSON file is valid (not corrupted)
• Check CSV format matches expected columns
• Try importing a smaller batch of assets

✨ Tips & Tricks

• Regular Snapshots - Take weekly snapshots to track long-term growth
• Export Often - Monthly backups prevent data loss
• Use Search - Quickly find assets in large portfolios
• Multiple Browsers - Use different browsers for separate portfolios (personal vs business)
• CSV Import - Faster than manual entry for 10+ assets
• Bookmark Pages - Save direct links to Charts or History pages
• Check News - Stay informed about your holdings' market movements

❓ Need Help?

If you need additional assistance:

• GitHub Issues - Report bugs or request features at GitHub Issues
• README - Check the README.md for more details
• Demo Data - Explore with pre-loaded demo assets to understand features