etf-trade-tracker/README.md

# ETF Trade Tracker

A web-based application for tracking ETF trades with multi-user authentication, portfolio management, and performance analysis.

## Features

- 🔐 **Multi-user Authentication** - Secure login system with admin and regular user roles
- 💼 **Portfolio Management** - Track your ETF positions, shares, and investments
- 📊 **Trade History** - Complete record of all buy/sell transactions
- 📈 **Gains/Losses Analysis** - Calculate performance with current market prices
- 📉 **Historical Price Tracking** - Store and view price update history with timestamps
- 💰 **Multi-Currency Support** - Full support for EUR, USD, and GBP currencies
- 🏦 **Cash Account Management** - Track savings accounts and cash transfers
- 📊 **Capital Gains Tax (CGT)** - Automatic CGT calculations with long-term rates
- 🎯 **Dashboard** - Overview of portfolio metrics and performance
- 👥 **Admin Panel** - User management for administrators
- 📱 **Responsive Design** - Works on desktop and mobile devices
- 💾 **SQLite Database** - Local database storage with user data isolation

## Screenshots

### Dashboard
Clean overview of your portfolio with key metrics and ETF breakdown.

### Trade Entry
Simple form to add new ETF trades with date/time and currency support (EUR/USD/GBP).

### Gains/Losses
Update current market prices to see real-time portfolio performance.

## Installation

### Option 1: Direct Installation

#### Prerequisites
- Node.js (v14 or higher)
- npm

#### Setup

1. Clone the repository:
```bash
git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker
```

2. Install dependencies:
```bash
npm install
```

3. Start the server:
```bash
npm start
```

4. Open your browser and navigate to:
```
http://localhost:3000
```

### Option 2: Container Installation (Podman/Docker)

#### Prerequisites
- Podman or Docker installed on your system

#### Using Podman

1. Clone the repository:
```bash
git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker
```

2. Build the container image:
```bash
podman build -t etf-tracker .
```

3. Run the container:
```bash
podman run -d \
  --name etf-tracker \
  -p 3000:3000 \
  -v etf_data:/app/data \
  etf-tracker
```

4. Open your browser and navigate to:
```
http://localhost:3000
```

#### Using Docker Compose

1. Clone the repository:
```bash
git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker
```

2. Start with docker-compose:
```bash
docker-compose up -d
```

3. Open your browser and navigate to:
```
http://localhost:3000
```

#### Container Management

**View logs:**
```bash
podman logs etf-tracker
# or
docker-compose logs
```

**Stop the container:**
```bash
podman stop etf-tracker
# or
docker-compose down
```

**Start the container:**
```bash
podman start etf-tracker
# or
docker-compose up -d
```

**Remove container and data:**
```bash
podman rm etf-tracker
podman volume rm etf_data
# or
docker-compose down -v
```

## Default Credentials

When you first run the application, a default admin user is created:

- **Username:** `admin`
- **Password:** `admin123`

⚠️ **Important:** Change the admin password after first login for security.

## Usage

### For Regular Users

1. **Login** - Use credentials provided by your administrator
2. **Add Trades** - Navigate to "Add Trade" to record buy/sell transactions
3. **View Portfolio** - Check your holdings and allocation in the Portfolio section
4. **Track Performance** - Update current prices in Gains/Losses to see real-time performance
5. **Export Data** - Export your trade history as JSON from Trade History

### For Administrators

1. **User Management** - Access Admin Panel from the sidebar to create/delete users
2. **Create Users** - Add new users with regular or admin privileges
3. **Monitor System** - View all users and their last login times

## API Endpoints

### Authentication
- `POST /api/login` - User login
- `POST /api/logout` - User logout  
- `GET /api/me` - Get current user info

### Trades
- `GET /api/trades` - Get user's trades
- `POST /api/trades` - Add new trade
- `DELETE /api/trades/:id` - Delete specific trade
- `DELETE /api/trades` - Clear all user trades

### Portfolio
- `GET /api/portfolio-summary` - Get portfolio summary

### Admin (Admin Only)
- `GET /api/admin/users` - List all users
- `POST /api/admin/users` - Create new user
- `DELETE /api/admin/users/:id` - Delete user

## Database Schema

### Users Table
- `id` - Primary key
- `username` - Unique username
- `password_hash` - Bcrypt hashed password
- `email` - Optional email address
- `is_admin` - Boolean admin flag
- `created_at` - Account creation timestamp
- `last_login` - Last login timestamp

### Trades Table  
- `id` - Primary key
- `user_id` - Foreign key to users table
- `etf_symbol` - ETF ticker symbol
- `trade_type` - 'buy' or 'sell'
- `shares` - Number of shares
- `price` - Price per share
- `currency` - 'EUR', 'USD', or 'GBP'
- `trade_datetime` - Date and time of trade
- `fees` - Optional trading fees
- `notes` - Optional trade notes
- `total_value` - Calculated total value
- `created_at` - Record creation timestamp

## Configuration

### Environment Variables

- `PORT` - Server port (default: 3000)

### Session Configuration

The application uses express-session with the following settings:
- Session secret: `etf-tracker-secret-key` (change in production)
- Session duration: 24 hours
- Secure cookies: disabled (enable for HTTPS)

## Security Features

- Password hashing using bcrypt
- Session-based authentication
- User data isolation
- Admin-only endpoints protection
- SQL injection prevention with parameterized queries

## Development

### Project Structure
```
├── server.js          # Express server and API routes
├── index.html         # Main HTML template
├── script.js          # Frontend JavaScript
├── styles.css         # CSS styles
├── package.json       # Dependencies and scripts
├── .gitignore         # Git ignore rules
└── README.md          # This file
```

### Running in Development Mode
```bash
npm run dev
```

This uses nodemon for automatic server restart on file changes.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## License

MIT License - see the code for details.

## Support

For issues or questions:
1. Check existing issues in the repository
2. Create a new issue with detailed description
3. Include steps to reproduce any bugs

## Changelog

### v1.2.0 (Latest)
- **Historical Price Tracking**: Store and view price update history for all ETFs
- **Price History Modal**: View timeline of price updates with timestamps
- **Persistent Pricing**: Automatically load latest prices on app startup
- **Multi-Currency Support**: Added British Pound (GBP) alongside EUR/USD
- **Enhanced UX**: Improved price update notifications and database persistence

### v1.1.0
- Comprehensive cash savings and transfers system
- Capital Gains Tax (CGT) calculations with 8+ year long-term rates
- Total holdings tracking across ETFs and cash accounts
- Enhanced portfolio analytics and reporting

### v1.0.0 (Initial Release)
- Multi-user authentication system
- ETF trade tracking
- Portfolio management
- Gains/losses calculation
- Admin panel
- Responsive design
- SQLite database integration