# myFidelityTracker

A modern web application for tracking and analyzing Fidelity brokerage account performance. Track individual trades, calculate P&L, and gain insights into your trading performance over time.

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
![React](https://img.shields.io/badge/react-18.2-blue.svg)

## Features

### Core Features
- **Multi-Account Support**: Manage multiple brokerage accounts in one place
- **CSV Import**: Import Fidelity transaction history via CSV upload or filesystem
- **Automatic Deduplication**: Prevents duplicate transactions when re-importing files
- **Position Tracking**: Automatically matches opening and closing transactions using FIFO
- **Real-Time P&L**: Calculate both realized and unrealized profit/loss with live market data
- **Performance Analytics**: View win rate, average win/loss, and top-performing trades
- **Interactive Dashboard**: Beautiful Robinhood-inspired UI with charts and metrics
- **Responsive Design**: Works seamlessly on desktop, tablet, and mobile

### Technical Features
- **Docker Deployment**: One-command setup with Docker Compose
- **Multi-Architecture**: Supports both amd64 and arm64 platforms
- **RESTful API**: FastAPI backend with automatic OpenAPI documentation
- **Type Safety**: Full TypeScript frontend for robust development
- **Database Migrations**: Alembic for version-controlled database schema
- **Market Data Integration**: Yahoo Finance API for current stock prices

## Screenshots

### Dashboard
View your account overview with key metrics and performance charts.

### Transaction History
Browse and filter all your transactions with advanced search.

### Import Interface
Drag-and-drop CSV files or import from the filesystem.

## Tech Stack

### Backend
- **FastAPI** - Modern Python web framework
- **SQLAlchemy** - SQL toolkit and ORM
- **PostgreSQL** - Relational database
- **Alembic** - Database migrations
- **Pandas** - Data manipulation and CSV parsing
- **yfinance** - Real-time market data

### Frontend
- **React 18** - UI library
- **TypeScript** - Type-safe JavaScript
- **Vite** - Fast build tool
- **TailwindCSS** - Utility-first CSS framework
- **React Query** - Data fetching and caching
- **Recharts** - Charting library
- **React Dropzone** - File upload component

### Infrastructure
- **Docker** - Containerization
- **Docker Compose** - Multi-container orchestration
- **Nginx** - Web server and reverse proxy
- **PostgreSQL 16** - Database server

## Quick Start

### Prerequisites
- Docker Desktop (or Docker Engine + Docker Compose)
- 4GB+ RAM available
- Port 3000, 8000, and 5432 available

### Installation

1. **Clone or download this repository**
   ```bash
   cd /path/to/fidelity
   ```

2. **Place your sample CSV file** (optional, for demo data)
   ```bash
   cp History_for_Account_X38661988.csv imports/
   ```

3. **Start the application**
   ```bash
   docker-compose up -d
   ```

   This will:
   - Build the backend, frontend, and database containers
   - Run database migrations
   - Start all services

4. **Seed demo data** (optional)
   ```bash
   docker-compose exec backend python seed_demo_data.py
   ```

5. **Access the application**
   - Frontend: http://localhost:3000
   - Backend API: http://localhost:8000
   - API Docs: http://localhost:8000/docs

### First-Time Setup

1. **Create an Account**
   - Navigate to the "Accounts" tab
   - Click "Add Account"
   - Enter your account details

2. **Import Transactions**
   - Go to the "Import" tab
   - Either:
     - Drag and drop a Fidelity CSV file
     - Place CSV files in the `./imports` directory and click "Import from Filesystem"

3. **View Dashboard**
   - Return to the "Dashboard" tab to see your portfolio performance

## Usage Guide

### Importing Transactions

#### CSV Upload (Recommended)
1. Navigate to the Import tab
2. Drag and drop your Fidelity CSV file or click to browse
3. The system will automatically:
   - Parse the CSV
   - Deduplicate existing transactions
   - Calculate positions
   - Update P&L metrics

#### Filesystem Import
1. Copy CSV files to the `./imports` directory on your host machine
2. Navigate to the Import tab
3. Click "Import from Filesystem"
4. All CSV files in the directory will be processed

### Understanding Positions

The application automatically tracks positions using FIFO (First-In-First-Out) logic:

- **Open Positions**: Currently held positions with unrealized P&L
- **Closed Positions**: Fully exited positions with realized P&L
- **Options**: Supports calls and puts, including assignments and expirations

### Viewing Analytics

#### Dashboard Metrics
- **Account Balance**: Current cash balance from latest transaction
- **Total P&L**: Combined realized and unrealized profit/loss
- **Win Rate**: Percentage of profitable closed trades
- **Open Positions**: Number of currently held positions

#### Charts
- **Balance History**: View account balance over time (6 months default)
- **Top Trades**: See your most profitable closed positions

## Development

### Local Development Setup

#### Backend
```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export POSTGRES_HOST=localhost
export POSTGRES_USER=fidelity
export POSTGRES_PASSWORD=fidelity123
export POSTGRES_DB=fidelitytracker

# Run migrations
alembic upgrade head

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

#### Frontend
```bash
cd frontend

# Install dependencies
npm install

# Start development server
npm run dev
```

Access the dev server at http://localhost:5173

### Database Access

Connect to PostgreSQL:
```bash
docker-compose exec postgres psql -U fidelity -d fidelitytracker
```

### View Logs

```bash
# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend
docker-compose logs -f frontend
docker-compose logs -f postgres
```

## API Documentation

### Interactive API Docs
Visit http://localhost:8000/docs for interactive Swagger UI documentation.

### Key Endpoints

#### Accounts
- `POST /api/accounts` - Create account
- `GET /api/accounts` - List accounts
- `GET /api/accounts/{id}` - Get account details
- `PUT /api/accounts/{id}` - Update account
- `DELETE /api/accounts/{id}` - Delete account

#### Import
- `POST /api/import/upload/{account_id}` - Upload CSV file
- `POST /api/import/filesystem/{account_id}` - Import from filesystem

#### Transactions
- `GET /api/transactions` - List transactions (with filters)
- `GET /api/transactions/{id}` - Get transaction details

#### Positions
- `GET /api/positions` - List positions (with filters)
- `GET /api/positions/{id}` - Get position details
- `POST /api/positions/{account_id}/rebuild` - Rebuild positions

#### Analytics
- `GET /api/analytics/overview/{account_id}` - Get account statistics
- `GET /api/analytics/balance-history/{account_id}` - Get balance history
- `GET /api/analytics/top-trades/{account_id}` - Get top trades
- `POST /api/analytics/update-pnl/{account_id}` - Update unrealized P&L

## Architecture

### Directory Structure
```
myFidelityTracker/
├── backend/               # FastAPI backend
│   ├── app/
│   │   ├── api/          # API endpoints
│   │   ├── models/       # SQLAlchemy models
│   │   ├── schemas/      # Pydantic schemas
│   │   ├── services/     # Business logic
│   │   ├── parsers/      # CSV parsers
│   │   └── utils/        # Utilities
│   ├── alembic/          # Database migrations
│   └── Dockerfile
├── frontend/             # React frontend
│   ├── src/
│   │   ├── components/   # React components
│   │   ├── api/          # API client
│   │   ├── types/        # TypeScript types
│   │   └── styles/       # CSS styles
│   ├── Dockerfile
│   └── nginx.conf
├── imports/              # CSV import directory
└── docker-compose.yml    # Docker configuration
```

### Data Flow

1. **Import**: CSV → Parser → Deduplication → Database
2. **Position Tracking**: Transactions → FIFO Matching → Positions
3. **Analytics**: Positions → Performance Calculator → Statistics
4. **Market Data**: Open Positions → Yahoo Finance API → Unrealized P&L

### Database Schema

#### accounts
- Account details and metadata

#### transactions
- Individual brokerage transactions
- Unique hash for deduplication

#### positions
- Trading positions (open/closed)
- P&L calculations

#### position_transactions
- Junction table linking positions to transactions

## Configuration

### Environment Variables

Create a `.env` file (or use `.env.example`):

```bash
# Database
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=fidelitytracker
POSTGRES_USER=fidelity
POSTGRES_PASSWORD=fidelity123

# API
API_V1_PREFIX=/api
PROJECT_NAME=myFidelityTracker

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Import Directory
IMPORT_DIR=/app/imports

# Market Data Cache (seconds)
MARKET_DATA_CACHE_TTL=60
```

## Troubleshooting

### Port Already in Use
If ports 3000, 8000, or 5432 are already in use:
```bash
# Stop conflicting services
docker-compose down

# Or modify ports in docker-compose.yml
```

### Database Connection Issues
```bash
# Reset database
docker-compose down -v
docker-compose up -d
```

### Import Errors
- Ensure CSV is in Fidelity format
- Check for encoding issues (use UTF-8)
- Verify all required columns are present

### Performance Issues
- Check Docker resource limits
- Increase PostgreSQL memory if needed
- Reduce balance history timeframe

## Deployment

### Production Considerations

1. **Use strong passwords** - Change default PostgreSQL credentials
2. **Enable HTTPS** - Add SSL/TLS certificates to Nginx
3. **Secure API** - Add authentication (JWT tokens)
4. **Backup database** - Regular PostgreSQL backups
5. **Monitor resources** - Set up logging and monitoring
6. **Update regularly** - Keep dependencies up to date

### Docker Multi-Architecture Build

Build for multiple platforms:
```bash
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t myfidelitytracker:latest .
```

## Roadmap

### Future Enhancements
- [ ] Additional brokerage support (Schwab, E*TRADE, Robinhood)
- [ ] Authentication and multi-user support
- [ ] AI-powered trade recommendations
- [ ] Tax reporting (wash sales, capital gains)
- [ ] Email notifications for imports
- [ ] Dark mode theme
- [ ] Export reports to PDF
- [ ] Advanced charting with technical indicators
- [ ] Paper trading / backtesting

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Guidelines
- Follow existing code style
- Add comments for complex logic
- Write type hints for Python code
- Use TypeScript for frontend code
- Test thoroughly before submitting

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues, questions, or suggestions:
- Open an issue on GitHub
- Check existing documentation
- Review API docs at `/docs`

## Acknowledgments

- Inspired by Robinhood's clean UI design
- Built with modern open-source technologies
- Market data provided by Yahoo Finance

---

**Disclaimer**: This application is for personal portfolio tracking only. It is not financial advice. Always consult with a financial advisor before making investment decisions.