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:

git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker

2. Install dependencies:

npm install

3. Start the server:

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:

git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker

2. Build the container image:

podman build -t etf-tracker .

3. Run the container:

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:

git clone git@teapot.hm.keyb.ie:kris/etf-trade-tracker.git
cd etf-trade-tracker

2. Start with docker-compose:

docker-compose up -d

3. Open your browser and navigate to:

http://localhost:3000

Container Management

View logs:

podman logs etf-tracker
# or
docker-compose logs

Stop the container:

podman stop etf-tracker
# or
docker-compose down

Start the container:

podman start etf-tracker
# or
docker-compose up -d

Remove container and data:

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

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