StockTrader: Virtual Stock Trading Simulator

Introduction

StockTrader is an educational and entertainment platform that allows users to simulate stock trading with virtual money. The application helps users learn the basics of stock trading, portfolio management, and analytics without financial risk.

Technologies and Architecture

Selected Technologies

• Backend: Java with Spring Boot

• Database: PostgreSQL (relational DB)

• Authentication: JWT via Spring Security, passwords encrypted with BCrypt

• Logging: SLF4J + Logback (centralized, standard format, sensitive data protection)

• Caching: Caffeine

• Containerization: Docker (separate containers for app and DB)

• Messaging: Apache Kafka (for events between microservices, event-driven architecture)

• Web Services: REST

• Design Patterns:

  • Strategy (Portfolio-service)
  • Factory (Stock-service)
  • State Machine (Transaction-service)
  • Iterator (Transaction-service)
  • Chain of Responsibility (Transaction-service)
  • Facade (Stock-service)

Architecture

Microservices-based architecture with Kafka integration

The application is built using a microservices architecture, where each service is independently deployable and encapsulates its own business logic. Services communicate asynchronously via Kafka, and synchronously via REST APIs, ensuring loose coupling and high scalability.

• Kafka provides independent processing of events (e.g., transactions and notifications).

• The Stock Service manages stock data. It provides CRUD operations for stocks, updates prices automatically and through external APIs, and publishes price update events to Kafka. Other services use it to fetch up-to-date stock information.

• The Transaction Service is responsible for handling buy and sell operations. It validates requests, interacts with the User Service to update balances, and with the Stock Service to fetch stock data. It also publishes transaction events to Kafka for further processing.

• The Portfolio Service manages users’ holdings. It updates positions after transactions, reacts to stock price updates, and evaluates portfolio value using different strategies (conservative, aggressive, balanced).

• The User Service handles authentication and user management. It issues JWT tokens for secure access and maintains user account balances, which are used by other services during transactions.

Functional Requirements

1. User Registration and Authentication

   • Register using username, email, and password (encrypted with BCrypt)
   • Authentication via JWT with token expiration and refresh support
   • Initial balance: $10,000 in virtual funds

2. Stock Operations

   • View a list of available stocks with current prices (updated every 60 seconds)
   • Buy and sell stocks with a 0.1% commission (balance and portfolio validation)
   • Transactions are processed and broadcasted via Kafka events

3. Portfolio Management

   • View portfolio details: name, quantity, average price, current value
   • View transaction history (buy/sell operations)

4. Administrative Functions

   • Add or remove stocks from the list (admin only)

Non-Functional Requirements

1. Security

   • Password encryption (BCrypt)
   • JWT-based authentication and role-based access control
   • Sensitive data is excluded from logs (e.g., passwords)

2. Performance

   • Stock prices update at least every 60 seconds

3. Reliability

   • All user and transaction data is stored in the database
   • Error handling and retry logic for Kafka events

4. Scalability

   • Supports up to 1,000 concurrent users
   • Possibility of horizontal service scaling

5. Logging

   • Centralized logging (SLF4J/Logback, standard format: timestamp, service name, log level, traceId)

6. Deployability

   • Docker Compose setup, separate containers for app, database, Kafka

7. Maintainability

   • Modular structure for ease of maintenance and feature extension

Deployment Instructions

Step 1: Clone the repository

git clone <your-repository>

Step 2: Configure environment variables

Set up database, Kafka connection settings in .env or via command-line/config files.

Step 3: Start with Docker Compose

docker-compose up --build

The following services will be started via docker-compose:

• Spring Boot application
• PostgreSQL
• Kafka

Step 4: Verify the launch

The application will be available at http://localhost:<8080>

Stopping the Application

docker-compose down

or

CTRL+C in the terminal where the application is running.

Initialization Guide

Step 1: Database Initialization

When the application starts for the first time, all necessary database schemas for each microservice are created automatically:

• user-service
• portfolio-service
• stock-service
• transaction-service

---

Step 2: Default Administrator

When starting the user-service, the application checks if an ADMIN user exists in the database. If no administrator is found, the application automatically creates a default admin account:

• Username: admin
• Email: admin@stocktrader.local
• Password: admin123

You can change these credentials by setting the following environment variables:

Variable	Default Value
ADMIN_USERNAME	admin
ADMIN_EMAIL	admin@stocktrader.local
ADMIN_PASSWORD	admin123

---

Step 3: First Login

After deployment, you can log in as the administrator using the following endpoint:

POST /api/auth/login

Request body:

{
  "username": "admin",
  "password": "admin123"
}

Logging

• Logging: All important actions in both stock and portfolio services (including data changes and queries) are logged in a standardized format at the controller and service levels.
• Data protection: Sensitive data (such as passwords) is excluded from logs.