Metadata-Version: 2.4
Name: degiro-portfolio
Version: 0.3.1
Summary: DEGIRO portfolio tracking and visualization application
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.115.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.2.0
Requires-Dist: plotly>=5.24.0
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: python-multipart>=0.0.21
Requires-Dist: requests>=2.31.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: twelvedata>=1.2.25
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: yfinance>=0.2.0
Provides-Extra: dev
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: invoke>=2.2.0; extra == 'dev'
Requires-Dist: myst-parser>=2.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-playwright>=0.4.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'dev'
Requires-Dist: sphinx>=7.0.0; extra == 'dev'
Requires-Dist: tomli>=2.0.0; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown

# DEGIRO Portfolio

A web application for tracking and visualizing your DEGIRO portfolio with interactive charts and performance analytics.

## Features

### Portfolio Management
- Import DEGIRO transaction exports from Excel spreadsheets
- Upload new transaction files directly via web interface
- Automatic fetching of historical stock prices using Yahoo Finance
- Automatic market index data loading on upload (S&P 500, Euro Stoxx 50)
- One-click market data updates for all holdings
- Multi-currency support (EUR, USD, SEK, GBP) with **live exchange rate conversion** (v0.3.0)
- SQLite database for efficient data storage and retrieval

### Portfolio Overview
- Real-time portfolio summary with total value and gain/loss
- Stock cards showing:
  - Current holdings and share count
  - Latest closing price with daily percentage change (▲/▼)
  - **Position value in EUR with live currency conversion** (NEW in v0.3.0)
  - Yahoo Finance ticker symbol (clickable → Google Finance)
  - Exchange information
  - Transaction count
- **Live exchange rates API** for accurate EUR conversion (NEW in v0.3.0)
- Market data status showing latest price update date
- Clickable company names linking to investor relations search
- Compact, space-efficient design

### Interactive Charts
- Candlestick price charts with buy/sell transaction markers
- Auto-refreshing stock charts (updates every minute)
- Investment tranche tracking showing individual purchase performance
- Position value percentage charts (where 100% = break even)
- Market index comparison (S&P 500, Euro Stoxx 50)
- Portfolio valuation over time with latest date annotation
- Automatic alignment of transaction markers with price bars
- Zoom, pan, and hover for detailed information
- Currency-aware visualization (transactions match price data)

## Screenshots

### Portfolio Overview
![Portfolio Overview](screenshots/portfolio-overview.png)
*Interactive portfolio dashboard showing holdings summary, stock price charts, position value percentage, investment tranche tracking, and market index comparison*

### Stock Detail View
![Stock Detail - Microsoft](screenshots/stock-detail-microsoft.png)
*Detailed view showing Microsoft's performance with multiple chart types including price history, position value %, investment tranches, and performance vs market indices*

## Technology Stack

- **Backend**: FastAPI (Python)
- **Database**: SQLite
- **Data Processing**: Pandas, SQLAlchemy
- **Stock Data**: yfinance
- **Frontend**: Vanilla JavaScript with Plotly.js for charts
- **Package Management**: uv

## Quick Start

```bash
# Install dependencies
uv sync

# Setup database and import data (one-time setup)
uv run invoke setup

# Start the server
./degiro-portfolio start

# Open browser to http://localhost:8000
```

## CLI Commands

The `degiro-portfolio` CLI provides easy server management:

```bash
./degiro-portfolio start    # Start the server
./degiro-portfolio stop     # Stop the server
./degiro-portfolio restart  # Restart the server
./degiro-portfolio status   # Check server status
```

## Invoke Tasks

Additional tasks are available via `invoke`:

```bash
# Server Management
uv run invoke start          # Start the server
uv run invoke stop           # Stop the server
uv run invoke restart        # Restart the server
uv run invoke status         # Check server status
uv run invoke dev            # Start development server with auto-reload
uv run invoke logs           # Show server logs

# Data Management
uv run invoke setup          # Import data and fetch prices
uv run invoke import-data    # Import transactions from Excel
uv run invoke fetch-prices   # Fetch latest stock prices
uv run invoke fetch-indices  # Fetch market index data
uv run invoke db-info        # Show database information

# Testing
uv run invoke test           # Run all tests
uv run invoke test-cov       # Run tests with coverage report
uv run invoke test-cov-html  # Generate HTML coverage report
uv run invoke test-unit      # Run only unit tests (fast)
uv run invoke test-integration  # Run browser integration tests

# Utilities
uv run invoke clean          # Clean generated files
uv run invoke --list         # Show all available tasks
```

## Testing

The project includes a comprehensive test suite covering UI, API endpoints, and interactive features with **70% code coverage**.

```bash
# Run all tests
uv run pytest tests/ -v

# Run tests with coverage report
uv run invoke test-cov

# Generate HTML coverage report
uv run invoke test-cov-html

# Run only unit tests (fast)
uv run invoke test-unit

# Run only integration tests (browser)
uv run invoke test-integration

# Run specific test file
uv run pytest tests/test_portfolio_overview.py -v
```

**Test Coverage (70%):**
- Portfolio overview page (17 tests)
- Stock charts and visualizations (15 tests)
- API endpoints (14 tests)
- Interactive features (19 tests)
- Unit tests for core modules (55+ tests)
  - FastAPI endpoints
  - Index fetching
  - Price fetching
  - Ticker resolution

See [tests/README.md](tests/README.md) for detailed testing documentation.

## Project Structure

```
degiro-portfolio/
├── src/degiro_portfolio/
│   ├── __init__.py
│   ├── database.py          # SQLAlchemy models and database config
│   ├── import_data.py       # Import transactions from Excel
│   ├── fetch_prices.py      # Fetch historical stock prices
│   ├── fetch_indices.py     # Fetch market index data
│   ├── main.py              # FastAPI application
│   └── static/
│       └── index.html       # Frontend interface
├── tests/
│   ├── conftest.py          # Pytest fixtures
│   ├── test_portfolio_overview.py  # UI tests
│   ├── test_stock_charts.py        # Chart tests
│   ├── test_api_endpoints.py       # API tests
│   ├── test_interactive_features.py # Interaction tests
│   └── README.md            # Testing documentation
├── degiro-portfolio         # CLI script for server management
├── tasks.py                 # Invoke tasks for automation
├── Transactions.xlsx        # Your transaction data file
├── example_data.xlsx        # Example demo data (AI & European stocks)
├── degiro-portfolio.db      # SQLite database (generated)
└── pyproject.toml           # Project dependencies
```

## Example Data

The repository includes `example_data.xlsx` with sample AI and European tech stock transactions for demonstration purposes. To try the application with this demo data:

```bash
# Import the example data
uv run python -c "from src.degiro_portfolio.import_data import import_transactions; import_transactions('example_data.xlsx')"

# Fetch prices for the stocks
uv run python src/degiro_portfolio/fetch_prices.py

# Fetch market indices
uv run python src/degiro_portfolio/fetch_indices.py

# Start the server
./degiro-portfolio start
```

The example portfolio includes:

**US Tech Stocks:**
- NVIDIA (NVDA) - 129 shares across 4 purchases
- Microsoft (MSFT) - 30 shares across 3 purchases
- Meta (META) - 68 shares across 2 purchases
- Alphabet/Google (GOOGL) - 57 shares across 2 purchases
- AMD - 97 shares across 3 purchases

**European Tech Stocks:**
- ASML (Netherlands) - 33 shares across 3 purchases
- SAP (Germany) - 75 shares across 2 purchases
- Infineon (Germany) - 400 shares across 3 purchases
- Nokia (Finland) - 900 shares across 2 purchases
- Ericsson (Sweden) - 1400 shares across 2 purchases
- STMicroelectronics (France) - 240 shares across 2 purchases

## Detailed Setup

1. **Install dependencies**:
   ```bash
   uv sync
   ```

2. **Import transaction data**:
   ```bash
   uv run invoke import-data
   # or: uv run python src/stockchart/import_data.py
   ```

3. **Fetch historical stock prices**:
   ```bash
   uv run invoke fetch-prices
   # or: uv run python src/stockchart/fetch_prices.py
   ```

4. **Start the web server**:
   ```bash
   ./degiro-portfolio start
   # or: uv run invoke start
   ```

5. **Open your browser**:
   Navigate to http://localhost:8000

## Usage

### Viewing Your Portfolio

Once the application is running, the main page displays:
- A grid of cards showing all current holdings with share counts
- Click on any stock card to view its detailed price chart
- Charts show candlestick price data with buy/sell transaction markers
- Statistics panel shows key metrics for the selected stock

### Updating Data

To update with new transactions:
```bash
# Re-import the updated Excel file
uv run python src/stockchart/import_data.py

# Fetch latest prices
uv run python src/stockchart/fetch_prices.py
```

## API Endpoints

- `GET /` - Main web interface
- `GET /api/holdings` - List all current stock holdings (with latest prices and daily changes)
- `GET /api/stock/{stock_id}/prices` - Historical prices for a stock
- `GET /api/stock/{stock_id}/transactions` - Transaction history for a stock
- `GET /api/stock/{stock_id}/chart-data` - Combined data for chart visualization (includes position percentage)
- `GET /api/portfolio-performance` - Portfolio-wide performance metrics
- `GET /api/market-data-status` - Get the most recent market data update date
- `POST /api/upload-transactions` - Upload new transaction Excel file
- `POST /api/update-market-data` - Fetch latest market data for all stocks and indices

## Database Schema

### Stocks Table
- Stock metadata (symbol, name, ISIN, exchange)

### Transactions Table
- Transaction history (date, quantity, price, fees, transaction type, currency)
- Links to stocks via foreign key

### Stock Prices Table
- Historical OHLCV (Open, High, Low, Close, Volume) data
- Links to stocks via foreign key

### Indices Table
- Market index metadata (symbol, name)

### Index Prices Table
- Historical closing prices for market indices
- Links to indices via foreign key

## Notes

- The application uses Yahoo Finance ticker symbols mapped from ISIN codes
- Historical data starts from the earliest transaction date for each stock
- Charts are interactive and support zooming, panning, and hovering for details
- Transaction markers are uniform size for clean visualization
- Stock cards display live prices and daily percentage changes
- Company names and ticker symbols are clickable for quick access to external resources
- See [PRICING_NOTES.md](PRICING_NOTES.md) for details on price data timing and differences from broker platforms
