💰 Personal Finance Platform

A full-stack microservices-based personal finance management platform with real-time stock portfolio tracking, budget management, currency conversion, Machine Learning-powered investment predictions, and async report generation.

Built with .NET 8, React, gRPC, RabbitMQ, PostgreSQL, SQL Server, Redis, and ML.NET.

👥 Team

Faculty of Mathematics, University of Belgrade

Name	Index Number
Stefan Drljevic	1042/2024
Lazar Kracunovic	1038/2024
Milos Obrenovic	1041/2024
Marko Radosavljevic	1010/2024

🌟 Features at a Glance

💼 Portfolio Management

Real-time stock trading with live market prices
Multi-currency support - Buy stocks in USD, EUR, GBP with automatic conversion
ML-powered predictions - FastTree Gradient Boosting algorithm for price forecasting
Smart recommendations - AI-driven BUY/SELL/HOLD suggestions
Visual analytics - Candlestick charts, pie charts, performance tracking

💳 Budget Management

Multi-wallet support - Separate wallets for different currencies
Expense tracking - Categorized transactions with spending analytics
Spending limits - Set monthly budgets per category
Recurring transactions - Automate regular income/expenses
Real-time balance - Instant updates across all services

💱 Currency Service

Live exchange rates - Real-time currency conversion
30+ currencies - Support for all major world currencies
Redis caching - Sub-millisecond conversion speeds
Historical rates - Track exchange rate changes over time

🧾 Report Generation

Async PDF reports - Generate transaction history reports
RabbitMQ integration - Event-driven report processing
Clean Architecture - Stateless microservice design
QuestPDF library - Professional PDF formatting

🔐 Security & Identity

JWT Authentication - Secure token-based auth
Role-based access - Admin and User roles
Refresh tokens - Seamless session management

🏗️ Architecture

Microservices Design Pattern

┌─────────────────────────────────────────────────────────────────┐
│                         Frontend (React)                         │
│                  Dashboard • Portfolio • Budget                  │
└────────────┬─────────────────────────────────────┬──────────────┘
             │ REST API                            │ REST API
             ▼                                     ▼
┌─────────────────────┐                 ┌─────────────────────┐
│   Portfolio Service │◄────gRPC────────┤   Budget Service    │
│  (Stock Management) │                 │  (Wallet & Expense) │
│   • .NET 8 REST API │                 │   • REST API        │
│   • ML.NET Predict  │                 │   • gRPC Service    │
│   • SQL Server DB   │                 │   • PostgreSQL DB   │
└──────┬──────┬───────┘                 └──────┬──────────────┘
       │      │                                 │
 gRPC  │      │ gRPC                      gRPC  │
       │      │                                 │
       ▼      ▼                                 ▼
┌──────────────────┐               ┌─────────────────────┐
│ MarketGateway    │               │  Currency Service   │
│ (Stock Prices)   │               │  (Exchange Rates)   │
│  • AlphaVantage  │               │   • REST + gRPC     │
│  • Finnhub API   │               │   • Redis Cache     │
│  • SQLite Cache  │               │   • External API    │
└──────────────────┘               └─────────────────────┘
                    
        ┌─────────────────────┐           ┌──────────────────┐
        │  IdentityServer     │           │  Report Service  │
        │  (Authentication)   │           │  (PDF Reports)   │
        │   • JWT Tokens      │           │   • RabbitMQ     │
        │   • User Management │           │   • QuestPDF     │
        │   • MSSQL Database  │           │   • Async Jobs   │
        └─────────────────────┘           └──────────────────┘
                                                   ▲
                                                   │ RabbitMQ
                                                   │
                                            (Event Publishers)

Communication Protocols

REST APIs - Frontend ↔ Services (HTTP/JSON)
gRPC - Service ↔ Service (HTTP/2, Protocol Buffers)
Message Queue - RabbitMQ for async events (Report generation)

📦 Services Breakdown

1. Portfolio Service 📈

Technology: .NET 8, Entity Framework Core, ML.NET, gRPC
Database: Microsoft SQL Server
Ports: 8006 (REST API)

Features:

Buy/sell stocks with real-time pricing
Portfolio valuation with gain/loss tracking
Machine Learning price predictions (FastTree algorithm)
Multi-currency portfolios with automatic conversion
ML-powered BUY/SELL/HOLD recommendations
Candlestick charts for technical analysis
Transaction history and audit trail

Key Endpoints:

POST   /api/portfolio/buy                    # Buy stocks
POST   /api/portfolio/sell                   # Sell stocks
GET    /api/portfolio/summary/{username}     # Portfolio summary
GET    /api/portfolio/predict/{symbol}       # ML price prediction
GET    /api/portfolio/recommendations        # ML recommendations
GET    /api/portfolio/candlestick/{symbol}   # Chart data

2. Budget Service 💳

Technology: .NET 8, Entity Framework Core, gRPC
Database: PostgreSQL
Ports: 8004 (REST API), 8005 (gRPC)

Features:

Multi-wallet management (USD, EUR, GBP, etc.)
Categorized expense tracking
Monthly spending limits with alerts
Recurring transactions (salary, bills, subscriptions)
Real-time balance updates
Spending analytics by category

Key Endpoints:

POST   /api/wallets                          # Create wallet
POST   /api/transaction                      # Create transaction
GET    /api/wallets/user/{userId}            # Get user wallets
POST   /api/spendinglimits                   # Set spending limit
GET    /api/wallets/{walletId}/summary/monthly # Monthly summary

gRPC Services:

CreateTransaction    # Create income/expense transaction
GetWalletState      # Get balance, limits, and wallet info

3. Currency Service 💱

Technology: .NET 8, Redis, External API Integration
Database: Redis (cache)
Ports: 8001 (REST API), 8002 (gRPC)

Features:

Real-time exchange rates for 30+ currencies
Sub-millisecond conversion via Redis cache
Automatic daily rate updates
Historical rate tracking
REST and gRPC interfaces

Key Endpoints:

GET    /api/currency/rates                   # All exchange rates
GET    /api/currency/convert                 # Currency conversion

gRPC Services:

GetConversion              # Convert between currencies
GetSpecificCurrencyRates   # Get rates for base currency

4. MarketGateway 📊

Technology: .NET 8, gRPC, Multi-vendor API Integration
Database: SQLite (cache)
Ports: 8007 (gRPC), 5288 (gRPC - local)

Features:

Unified API for multiple stock data vendors
AlphaVantage and Finnhub integration
Smart caching (24-hour freshness)
Rate limiting and usage tracking
OHLCV data for candlestick charts
Mock fallback for demo API keys

gRPC Services:

Fetch    # Get quote or OHLCV data for symbols

5. Report Service 🧾

Technology: .NET 8, MassTransit, RabbitMQ, QuestPDF
Database: None (stateless service)
Ports: 8008 (REST API)

Features:

Asynchronous PDF report generation
RabbitMQ message consumption
Transaction history reports
Clean Architecture implementation
Automatic file storage
Email-ready report delivery

Key Capabilities:

TransactionsReportConsumer    # Consumes transaction report events
GeneratePdfReport            # Creates formatted PDF reports
SaveReportLocally           # Stores reports in /app/reports

Message Queue:

Queue: transactionsreport-queue
Event: TransactionsReportEvent
  - UserId, UserName, EmailAddress
  - TransactionItems[] (Amount, Date, Category, etc.)

6. IdentityServer 🔐

Technology: ASP.NET Identity, JWT
Database: Microsoft SQL Server
Ports: 8003 (REST API)

Features:

User registration and login
JWT token generation
Refresh token support
Role-based authorization (Admin, User)
Secure password hashing

Key Endpoints:

POST   /api/v1/authentication/registeruser   # Register new user
POST   /api/v1/authentication/login          # Login & get JWT
GET    /api/v1/user/{username}               # Get user details

🛠️ Technology Stack

Backend

Service	Language	Framework	Database	Protocol
Portfolio	C# (.NET 8)	ASP.NET Core	SQL Server	REST + gRPC Client
Budget	C# (.NET 8)	ASP.NET Core	PostgreSQL	REST + gRPC Server
Currency	C# (.NET 8)	ASP.NET Core	Redis	REST + gRPC Server
MarketGateway	C# (.NET 8)	ASP.NET Core	SQLite	gRPC Server
Report	C# (.NET 8)	ASP.NET Core	None (stateless)	RabbitMQ Consumer
IdentityServer	C# (.NET 8)	ASP.NET Identity	SQL Server	REST

Frontend

React 18 with TypeScript
Vite for build tooling
React Router for navigation
JWT Authentication with refresh tokens
Axios for HTTP requests

Infrastructure

Docker Compose - Multi-container orchestration
gRPC (HTTP/2) - High-performance service communication
RabbitMQ - Message queue for async operations
Redis - High-speed caching
Protocol Buffers - Efficient binary serialization

Machine Learning

ML.NET 3.0 - Microsoft's ML framework
FastTree Gradient Boosting - Ensemble learning algorithm
Auto-training - Models train on first request
Intelligent caching - 24-hour model lifetime

🚀 Quick Start

Prerequisites

Docker Desktop
.NET 8 SDK
Node.js 18+ (for frontend)

1. Start All Services (Docker)

cd Personal-Finance

# Start all infrastructure and services
docker-compose up -d

# Wait for databases to initialize (first time only)
sleep 60

# Check all services are running
docker-compose ps

2. Access Services

Service	URL	Description
Frontend	http://localhost:3000	React dashboard
Portfolio API	http://localhost:8006	Stock trading endpoints
Portfolio Swagger	http://localhost:8006/swagger	API documentation
Budget API	http://localhost:8004	Budget management
Currency API	http://localhost:8001	Exchange rates
Report API	http://localhost:8008	Report generation service
IdentityServer	http://localhost:8003	Authentication
RabbitMQ Dashboard	http://localhost:15672	Message queue management

3. Run Frontend (Development)

cd Frontend
npm install
npm run dev
# Opens http://localhost:3000

4. Test the System

# Health check
curl http://localhost:8006/api/portfolio/health

# Get ML price prediction for AAPL
curl http://localhost:8006/api/portfolio/predict/AAPL

# Get portfolio summary
curl http://localhost:8006/api/portfolio/summary/john_doe

# Buy stocks
curl -X POST http://localhost:8006/api/portfolio/buy \
  -H "Content-Type: application/json" \
  -d '{"username":"john_doe","symbol":"AAPL","quantity":10}'

📊 Service Dependencies

Frontend
  └── Portfolio API
        ├── MarketGateway (stock prices)
        ├── Budget gRPC (balance validation)
        ├── Currency gRPC (multi-currency)
        └── IdentityServer (user resolution)

Budget gRPC
  ├── Currency gRPC (conversion)
  └── RabbitMQ (publish report events)

Report Service
  └── RabbitMQ (consume report events)

Currency gRPC
  └── Redis (cache)

IdentityServer
  └── MSSQL (user data)

🎓 Key Integrations

1. Portfolio ↔ Budget Integration

Check funds before stock purchase via GetWalletState gRPC
Deduct money when buying stocks via CreateTransaction (EXPENSE)
Add money when selling stocks via CreateTransaction (INCOME)
Multi-currency - Automatic conversion between stock and wallet currencies

2. Portfolio ↔ MarketGateway Integration

Real-time stock quotes via gRPC
OHLCV historical data for ML training
Mock fallback for demo API keys (Price=$100, Open=$98, etc.)

3. Budget ↔ Currency Integration

Automatic currency conversion for multi-currency wallets
Spending totals calculated in wallet's base currency

4. Portfolio ↔ IdentityServer Integration

Username → UserId resolution
User details cached for performance

5. Budget ↔ Report Service Integration

Async report generation via RabbitMQ message queue
Event-driven architecture - Budget publishes TransactionsReportEvent
PDF generation with QuestPDF library
Stateless service - Reports saved to /app/reports directory
Email-ready - Reports can be attached to email notifications

🤖 Machine Learning Features

Price Prediction Algorithm

FastTree Gradient Boosting with 100 decision trees
Trains on 100 days of historical data
Features analyzed: Price, moving averages (5/10/20 day), momentum, volatility
Confidence scoring based on price stability
Auto-caching - First request trains (3-5s), subsequent requests instant

Smart Recommendations

GET /api/portfolio/recommendations?symbols=AAPL,TSLA,MSFT,IBM

Returns:

BUY signals - Stocks ML predicts will rise (>2%)
SELL signals - Stocks ML predicts will fall (<-2%)
HOLD signals - Stocks with no clear trend
Sorted by confidence × magnitude for strongest signals first

📱 API Examples

Buy Stock with Budget Validation

curl -X POST http://localhost:8006/api/portfolio/buy \
  -H "Content-Type: application/json" \
  -d '{
    "username": "john_doe",
    "symbol": "AAPL",
    "quantity": 10
  }'

What happens:

✅ IdentityServer resolves "john_doe" → userId
✅ MarketGateway fetches current AAPL price ($227.50)
✅ Budget checks if user has $2,275 available
✅ Budget deducts $2,275 from wallet (EXPENSE transaction)
✅ Portfolio saves position to database
✅ Returns transaction details

Multi-Currency Portfolio Summary

curl "http://localhost:8006/api/portfolio/summary/alice?baseCurrency=EUR"

Result:

{
  "username": "alice",
  "baseCurrency": "EUR",
  "totalInvested": 1850.43,
  "currentValue": 1923.17,
  "totalGainLoss": 72.74,
  "gainLossPercentage": 3.93,
  "positions": [
    {
      "symbol": "AAPL",
      "quantity": 10,
      "averagePurchasePrice": 225.00,
      "currentPrice": 227.50,
      "currency": "USD",
      "totalInvested": 1924.65,
      "currentValue": 1945.98,
      "gainLoss": 21.33,
      "gainLossPercentage": 1.11
    }
  ]
}

All USD values automatically converted to EUR!

🗄️ Database Schema

Portfolio Database (SQL Server)

Positions
  - Id, Username, Symbol, Quantity
  - AveragePurchasePrice, Currency
  - FirstPurchaseDate, LastUpdated

Transactions
  - Id, Username, Symbol, Type (BUY/SELL)
  - Quantity, PricePerShare, Currency
  - TransactionDate

Budget Database (PostgreSQL)

Wallets
  - Id, UserId, Name, Currency
  - CurrentBalance

Transactions
  - Id, UserId, WalletId, Amount
  - TransactionType (Income/Expense)
  - CategoryName, Currency, Date

Categories
  - Id, UserId, Name

SpendingLimits
  - Id, WalletId, CategoryName
  - Amount, Month, Year

RecurringTransactions
  - Id, UserId, WalletId, Amount
  - Frequency (Weekly/Monthly/Yearly)
  - StartDate, NextDueDate, EndDate

🔧 Configuration

Environment Variables (Docker)

Portfolio:

ASPNETCORE_ENVIRONMENT: Development
ConnectionStrings:PortfolioDb: "Server=mssql;Database=PortfolioDb;..."
MarketGatewayUrl: http://marketgateway.core:8080
BudgetServiceUrl: http://budget.grpc:8080
CurrencyServiceUrl: http://currency.grpc:8080
IdentityServerUrl: http://identityserver:8080

Budget:

ConnectionStrings:DefaultConnection: "Host=budget-db;Port=5432;Database=BudgetDb;..."
ServiceUrls:CurrencyService: http://currency.grpc:8080

📈 Performance Characteristics

ML Predictions

First prediction: 3-5 seconds (model training)
Subsequent predictions: <100ms (cached model)
Model refresh: Auto-retrains after 24 hours

gRPC Communication

Latency: 5-20ms (service-to-service)
Throughput: 10,000+ requests/second
Serialization: Protocol Buffers (10x faster than JSON)

Currency Conversion

With cache: <1ms
Cache miss: ~50ms (external API call)
Cache duration: 24 hours

🌐 Port Mapping

Port	Service	Protocol	Description
8001	Currency.API	REST	Exchange rate API
8002	Currency.GRPC	gRPC	Currency conversion
8003	IdentityServer	REST	Authentication
8004	Budget.API	REST	Budget management
8005	Budget.GRPC	gRPC	Budget service
8006	Portfolio.API	REST	Stock portfolio
8007	MarketGateway	gRPC	Market data
8008	Report.API	REST	Report generation
1435	MSSQL	TCP	SQL Server
5432	PostgreSQL	TCP	Budget database
6379	Redis	TCP	Currency cache
5672	RabbitMQ	AMQP	Message queue
15672	RabbitMQ UI	HTTP	Management dashboard

📚 Documentation

Each service has detailed documentation:

Services/Portfolio/README.md - Portfolio service guide
Services/Budget/README.md - Budget service guide
Services/Currency/README.md - Currency service guide
Services/Report/README.md - Report service guide
MarketGateway/Readme.md - MarketGateway guide

🎯 Use Cases

For Students

✅ Microservices architecture demonstration
✅ gRPC vs REST comparison
✅ Machine Learning integration
✅ Multi-database management
✅ Real-world financial domain modeling

For Developers

✅ Clean Architecture (Domain, Application, Infrastructure)
✅ CQRS patterns
✅ Repository pattern
✅ Dependency injection
✅ Docker containerization

For Finance Enthusiasts

✅ Real-time portfolio tracking
✅ AI-powered investment insights
✅ Multi-currency support
✅ Comprehensive budget management

🐳 Docker Commands

# Start everything
docker-compose up -d

# View logs
docker-compose logs -f portfolio.api
docker-compose logs -f budget.grpc

# Restart a service
docker-compose restart portfolio.api

# Rebuild and restart
docker-compose build portfolio.api && docker-compose up -d portfolio.api

# Stop everything
docker-compose down

# Clean everything (including volumes)
docker-compose down -v

🔍 Service Health Checks

# Portfolio
curl http://localhost:8006/api/portfolio/health

# Budget (REST)
curl http://localhost:8004/weatherforecast

# Currency
curl http://localhost:8001/api/currency/rates

# Report
curl http://localhost:8008/swagger

# IdentityServer
curl http://localhost:8003/health

# MarketGateway
curl http://localhost:8007/health

# RabbitMQ Management UI
open http://localhost:15672  # guest/guest

🎨 Frontend Features

Dashboard - Overview of finances and investments
Portfolio Page - Stock holdings with real-time prices
Budget Page - Expense tracking and wallet management
Transactions - Complete financial history
Analytics - Charts and visualizations
Dark Mode - Beautiful UI with theme switching

🚧 Development Setup (Local)

Run Services Locally

# 1. Start databases
docker-compose up -d mssql budget-db currency-db

# 2. Start Currency service
cd Personal-Finance/Services/Currency/Currency.GRPC
dotnet run  # Port 8002

# 3. Start Budget GRPC
cd Personal-Finance/Services/Budget/Budget.GRPC
dotnet run  # Port 5239 (local) / 8005 (docker)

# 4. Start MarketGateway
cd MarketGateway/MarketGateway.Core
dotnet run  # Port 5288

# 5. Start Portfolio API
cd Personal-Finance/Services/Portfolio/Portfolio.API
dotnet run  # Port 5086 (local)

# 6. Start Frontend
cd Frontend
npm run dev  # Port 3000

🎓 Academic Highlights

Demonstrated Concepts

Microservices Architecture - Service independence, scalability
gRPC Communication - High-performance RPC vs REST
Domain-Driven Design - Clear domain boundaries
CQRS - Command Query Responsibility Segregation
Event-Driven - Async communication patterns
Multi-Database - Polyglot persistence (SQL Server, PostgreSQL, SQLite, Redis)
Machine Learning - Real-world ML integration
Security - JWT, authentication, authorization

📊 System Metrics

Total Services: 9 microservices (Portfolio, Budget, Currency, MarketGateway, Report, IdentityServer + infrastructure)
Total Databases: 4 (SQL Server, PostgreSQL, SQLite, Redis)
API Endpoints: 40+ REST endpoints
gRPC Services: 6 gRPC service definitions
Message Queues: RabbitMQ with async event processing
Lines of Code: ~15,000+ (backend) + ~5,000+ (frontend)
Supported Currencies: 30+
ML Models: FastTree with 100 decision trees

🤝 Contributing

This is a university project demonstrating modern software architecture patterns.

📝 License

Academic project - MATF (Faculty of Mathematics, University of Belgrade)

🌟 Star Features

✅ Comprehensive error handling - Graceful failures
✅ Multi-currency support - Real-world complexity
✅ Machine Learning - Cutting-edge tech
✅ Docker ready - One command deployment
✅ API documentation - Swagger for all REST APIs

Perfect for university presentations, job portfolios, or learning microservices! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github		.github
Frontend		Frontend
MarketGateway		MarketGateway
Personal-Finance		Personal-Finance
.editorconfig		.editorconfig
.gitignore		.gitignore
.gitlint		.gitlint
.pre-commit-config.yaml		.pre-commit-config.yaml
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

💰 Personal Finance Platform

👥 Team

🌟 Features at a Glance

💼 Portfolio Management

💳 Budget Management

💱 Currency Service

🧾 Report Generation

🔐 Security & Identity

🏗️ Architecture

Microservices Design Pattern

Communication Protocols

📦 Services Breakdown

1. Portfolio Service 📈

2. Budget Service 💳

3. Currency Service 💱

4. MarketGateway 📊

5. Report Service 🧾

6. IdentityServer 🔐

🛠️ Technology Stack

Backend

Frontend

Infrastructure

Machine Learning

🚀 Quick Start

Prerequisites

1. Start All Services (Docker)

2. Access Services

3. Run Frontend (Development)

4. Test the System

📊 Service Dependencies

🎓 Key Integrations

1. Portfolio ↔ Budget Integration

2. Portfolio ↔ MarketGateway Integration

3. Budget ↔ Currency Integration

4. Portfolio ↔ IdentityServer Integration

5. Budget ↔ Report Service Integration

🤖 Machine Learning Features

Price Prediction Algorithm

Smart Recommendations

📱 API Examples

Buy Stock with Budget Validation

Multi-Currency Portfolio Summary

🗄️ Database Schema

Portfolio Database (SQL Server)

Budget Database (PostgreSQL)

🔧 Configuration

Environment Variables (Docker)

📈 Performance Characteristics

ML Predictions

gRPC Communication

Currency Conversion

🌐 Port Mapping

📚 Documentation

🎯 Use Cases

For Students

For Developers

For Finance Enthusiasts

🐳 Docker Commands

🔍 Service Health Checks

🎨 Frontend Features

🚧 Development Setup (Local)

Run Services Locally

🎓 Academic Highlights

Demonstrated Concepts

📊 System Metrics

🤝 Contributing

📝 License

🌟 Star Features

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Packages