added README
This commit is contained in:
Matthias Hinrichs
@@ -0,0 +1,216 @@
|
||||
Portfolio Tracker
|
||||
|
||||
A comprehensive portfolio management application built with Go that allows users to track their investment portfolios across multiple currencies with real-time data integration.
|
||||
|
||||
## 🚀 Features
|
||||
|
||||
### Portfolio Management
|
||||
- **Multiple Portfolios**: Create and manage multiple investment portfolios
|
||||
- **Multi-Currency Support**: Track investments in different currencies with automatic conversion
|
||||
- **Transaction Tracking**: Record buy, sell, and dividend transactions
|
||||
- **Real-time Data**: Integration with Yahoo Finance API for live stock prices and data
|
||||
|
||||
### Currency Conversion
|
||||
- **Automatic Currency Detection**: Automatically detects stock currencies from Yahoo Finance
|
||||
- **Real-time Exchange Rates**: Fetches current exchange rates from `exchangerate-api.com`
|
||||
- **Smart Caching**: 1-hour cache for exchange rates to optimize performance
|
||||
- **160+ Currencies Supported**: Including major currencies like USD, EUR, GBP, JPY, CHF
|
||||
|
||||
### User Experience
|
||||
- **User Authentication**: Secure registration and login system
|
||||
- **Responsive Design**: Clean, modern UI built with Tabler CSS framework
|
||||
- **Stock Search**: Advanced search functionality for stocks and securities
|
||||
- **Interactive Charts**: Stock price and dividend charts powered by ApexCharts
|
||||
- **Transaction Management**: Edit and delete transactions with full audit trail
|
||||
|
||||
## 🛠️ Technology Stack
|
||||
|
||||
- **Backend**: Go 1.24.4
|
||||
- **Database**: SQLite with GORM ORM
|
||||
- **Templates**: Templ templating engine
|
||||
- **Frontend**: Tabler CSS framework
|
||||
- **Charts**: ApexCharts
|
||||
- **APIs**: Yahoo Finance, ExchangeRate API
|
||||
- **Session Management**: Gorilla Sessions
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- Go 1.24.4 or later
|
||||
- Git
|
||||
|
||||
## 🔧 Installation
|
||||
|
||||
1. **Clone the repository**:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd portfolio-tracker
|
||||
```
|
||||
|
||||
2. **Install dependencies**:
|
||||
```bash
|
||||
go mod download
|
||||
```
|
||||
|
||||
3. **Install Templ CLI** (for template generation):
|
||||
```bash
|
||||
go install github.com/a-h/templ/cmd/templ@latest
|
||||
```
|
||||
|
||||
4. **Generate templates** (if needed):
|
||||
```bash
|
||||
templ generate
|
||||
```
|
||||
|
||||
5. **Run the application**:
|
||||
```bash
|
||||
go run cmd/app/main.go
|
||||
```
|
||||
|
||||
6. **Access the application**:
|
||||
Open your browser and navigate to `http://localhost:8080`
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
portfolio-tracker/
|
||||
├── cmd/app/main.go # Application entry point
|
||||
├── internal/
|
||||
│ ├── handler/ # HTTP handlers
|
||||
│ │ ├── api.go # API endpoints
|
||||
│ │ ├── auth.go # Authentication handlers
|
||||
│ │ ├── portfolio.go # Portfolio management
|
||||
│ │ └── pages.go # Page handlers
|
||||
│ ├── model/ # Database models
|
||||
│ │ ├── user.go # User model
|
||||
│ │ ├── portfolio.go # Portfolio model
|
||||
│ │ ├── activities.go # Transaction model
|
||||
│ │ └── models.go # Yahoo Finance response models
|
||||
│ ├── util/ # Utility functions
|
||||
│ │ ├── currency.go # Currency conversion utilities
|
||||
│ │ └── yahoo-utils.go # Yahoo Finance API utilities
|
||||
│ ├── session/ # Session management
|
||||
│ └── web/templates/ # Templ templates
|
||||
├── docs/ # Documentation
|
||||
├── data/ # SQLite database (auto-created)
|
||||
├── go.mod # Go module file
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 🎯 Usage
|
||||
|
||||
### Getting Started
|
||||
|
||||
1. **Register an Account**: Create a new user account or login with existing credentials
|
||||
2. **Create a Portfolio**: Set up your first portfolio with a name, base currency, and description
|
||||
3. **Add Transactions**: Start tracking your investments by adding buy, sell, or dividend transactions
|
||||
4. **Search Stocks**: Use the search functionality to find stocks and add them to your portfolio
|
||||
5. **Monitor Performance**: View your portfolio summary and track performance across currencies
|
||||
|
||||
### Currency Conversion
|
||||
|
||||
The application automatically:
|
||||
- Detects the currency of stocks from Yahoo Finance
|
||||
- Converts transaction amounts to your portfolio's base currency
|
||||
- Displays both original and converted amounts for transparency
|
||||
- Updates exchange rates hourly for accuracy
|
||||
|
||||
### Stock Data
|
||||
|
||||
- **Real-time Prices**: Current stock prices and market data
|
||||
- **Historical Charts**: Price movement over time
|
||||
- **Dividend History**: Track dividend payments and history
|
||||
- **Company Information**: Basic company details and metrics
|
||||
|
||||
## 🔑 API Endpoints
|
||||
|
||||
### Public Endpoints
|
||||
- `GET /` - Dashboard
|
||||
- `POST /user/register` - User registration
|
||||
- `POST /user/login` - User login
|
||||
- `POST /user/logout` - User logout
|
||||
|
||||
### Portfolio Management
|
||||
- `GET /portfolio/{id}` - View portfolio details
|
||||
- `POST /portfolio/create` - Create new portfolio
|
||||
- `POST /portfolio/transaction` - Add transaction
|
||||
- `POST /portfolio/transaction/edit` - Edit transaction
|
||||
- `POST /portfolio/transaction/delete` - Delete transaction
|
||||
|
||||
### API Endpoints
|
||||
- `GET /api/yahoo` - Get stock data from Yahoo Finance
|
||||
- `GET /api/stocksearch` - Search for stocks
|
||||
- `GET /api/yahoomaxdividends` - Get dividend data
|
||||
- `POST /api/admin/clear-currency-cache` - Clear currency cache
|
||||
- `GET /api/admin/currency-cache-info` - Get cache information
|
||||
|
||||
## 🌍 Currency Support
|
||||
|
||||
The application supports 160+ currencies including:
|
||||
|
||||
| Currency | Code | Symbol |
|
||||
|----------|------|--------|
|
||||
| US Dollar | USD | $ |
|
||||
| Euro | EUR | € |
|
||||
| British Pound | GBP | £ |
|
||||
| Japanese Yen | JPY | ¥ |
|
||||
| Swiss Franc | CHF | CHF |
|
||||
| Canadian Dollar | CAD | C$ |
|
||||
| Australian Dollar | AUD | A$ |
|
||||
| And many more... | | |
|
||||
|
||||
## 🚦 Development
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
go test ./internal/util/ -v
|
||||
```
|
||||
|
||||
### Generating Templates
|
||||
```bash
|
||||
templ generate
|
||||
```
|
||||
|
||||
### Database
|
||||
The application uses SQLite and automatically creates the database file at `data/portfolio.db` on first run. Database migrations are handled automatically by GORM.
|
||||
|
||||
## 📊 Features in Detail
|
||||
|
||||
### Multi-Currency Portfolio Management
|
||||
- Create portfolios in different base currencies
|
||||
- Automatic currency conversion for cross-currency transactions
|
||||
- Real-time exchange rate fetching and caching
|
||||
- Clear indication of converted vs. original amounts
|
||||
|
||||
### Transaction Management
|
||||
- Support for Buy, Sell, and Dividend transactions
|
||||
- Automatic stock currency detection
|
||||
- Edit and delete capabilities
|
||||
- Transaction history and audit trail
|
||||
|
||||
### Stock Integration
|
||||
- Yahoo Finance API integration
|
||||
- Real-time stock prices and data
|
||||
- Stock search functionality
|
||||
- Price and dividend charts
|
||||
- Company information display
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## 📝 License
|
||||
|
||||
This project is licensed under the MIT License - see the LICENSE file for details.
|
||||
|
||||
## 🔗 External APIs
|
||||
|
||||
- **Yahoo Finance**: Stock data, prices, and company information
|
||||
- **ExchangeRate API**: Currency exchange rates (free tier, no API key required)
|
||||
|
||||
## ⚠️ Disclaimer
|
||||
|
||||
This application is for educational and personal use only. Stock prices and financial data are provided for informational purposes. Always consult with financial professionals before making investment decisions.
|
||||
Reference in New Issue
Block a user