Transactions API

A comprehensive transactions API built with Quarkus, featuring reactive programming, clean architecture, and multiple interfaces (REST API & MCP).

🏗️ Architecture Overview

This system follows Clean Architecture principles with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                    Interface Layer                          │
│  ┌─────────────────┐           ┌─────────────────┐         │
│  │   REST API      │           │   MCP Server    │         │
│  │   Controllers   │           │   Tools         │         │
│  └─────────────────┘           └─────────────────┘         │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                  Application Layer                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │  Transaction    │  │    Position     │  │  Portfolio   │ │
│  │   Use Cases     │  │   Use Cases     │  │  Use Cases   │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                    Domain Layer                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │   Transaction   │  │    Position     │  │   Currency   │ │
│  │     Model       │  │     Model       │  │    Enums     │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│                Infrastructure Layer                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │   PostgreSQL    │  │     Panache     │  │     JSON     │ │
│  │   Database      │  │   Repositories  │  │   Mappers    │ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

🚀 Features

💼 Portfolio Management

✅ Transaction Management: Create, read, update, delete transactions
✅ Position Tracking: Automatic position calculation from transactions
✅ Market Data: Real-time price updates and P&L calculations
✅ Portfolio Summary: Comprehensive portfolio metrics and analytics
✅ Multi-Currency Support: USD, EUR, GBP with proper handling

🔄 Reactive Architecture

✅ Non-blocking I/O: Built with Quarkus reactive stack
✅ Async Operations: All database operations are reactive
✅ Performance: High throughput with efficient resource usage
✅ Scalability: Designed for cloud-native deployments

🌐 Multiple Interfaces

✅ REST API: Complete HTTP API for web/mobile applications
✅ MCP Server: Model Context Protocol for AI integrations
✅ Clean Separation: Both interfaces use same business logic

🗄️ Data Management

✅ PostgreSQL: Production-ready database with custom types
✅ Schema Management: Comprehensive database schema with triggers
✅ Automatic Calculations: Position recalculation via database triggers
✅ Data Integrity: Proper constraints and validation

🛠️ Tech Stack

Layer	Technology
Framework	Quarkus (Reactive)
Language	Java 21
Database	PostgreSQL 14+
ORM	Hibernate Reactive with Panache
API	JAX-RS (REST) + MCP Protocol
Build	Gradle
Testing	JUnit 5 + TestContainers

📦 Project Structure

src/main/java/com/portfolio/
├── application/usecase/          # Business Use Cases
│   ├── transaction/              # Transaction operations
│   ├── position/                 # Position operations
│   └── portfolio/                # Portfolio operations
├── domain/                       # Domain Models & Logic
│   ├── model/                    # Core entities
│   ├── port/                     # Repository interfaces
│   └── valueobject/              # Value objects
└── infrastructure/               # External Interfaces
    ├── persistence/              # Database implementation
    │   ├── entity/               # JPA entities
    │   ├── repository/           # Panache repositories
    │   └── adapter/              # Repository adapters
    ├── rest/                     # REST API
    │   ├── dto/                  # Data transfer objects
    │   └── mapper/               # Domain ↔ DTO mapping
    └── mcp/                      # MCP Server
        ├── dto/                  # MCP protocol DTOs
        ├── tools/                # MCP tool registry
        └── config/               # MCP configuration

🚀 Quick Start

Prerequisites

Java 21+
PostgreSQL 14+
Docker (optional, for database)

1. Database Setup

# Option A: Using Docker
docker-compose up -d

# Option B: Local PostgreSQL
createdb portfolio_db
psql portfolio_db < src/main/resources/db/migration/schema.sql

2. Application Configuration

# application.properties
quarkus.datasource.reactive.url=postgresql://localhost:5432/portfolio_db
quarkus.datasource.username=portfolio_user
quarkus.datasource.password=your_password

3. Run the Application

# Development mode (with live reload)
./gradlew quarkusDev

# Production mode
./gradlew build
java -jar build/quarkus-app/quarkus-run.jar

4. Verify Installation

# Test REST API
./scripts/quick-test.sh

# Test MCP Server
./scripts/test-mcp.sh

📡 API Documentation

🌐 REST API Endpoints

Transactions (`/api/transactions`)

POST   /api/transactions              # Create transaction
GET    /api/transactions              # List all transactions
GET    /api/transactions/{id}         # Get transaction by ID
PUT    /api/transactions/{id}         # Update transaction
DELETE /api/transactions/{id}         # Delete transaction
GET    /api/transactions/ticker/{ticker}    # Get by ticker
GET    /api/transactions/search       # Search with filters

Positions (`/api/positions`)

GET    /api/positions                 # List all positions
GET    /api/positions/active          # List active positions
GET    /api/positions/{id}            # Get position by ID
GET    /api/positions/ticker/{ticker} # Get position by ticker
PUT    /api/positions/ticker/{ticker}/price # Update market price
POST   /api/positions/ticker/{ticker}/recalculate # Recalculate position

Portfolio (`/api/portfolio`)

GET    /api/portfolio/summary         # Complete portfolio summary
GET    /api/portfolio/summary/active  # Active portfolio summary

🤖 MCP Server Tools

Transaction Tools

create_transaction - Create a new transaction
get_transaction - Get transaction by ID
update_transaction - Update existing transaction
delete_transaction - Delete transaction
get_transactions_by_ticker - Get transactions for ticker
search_transactions - Search with filters

Position Tools

get_all_positions - Get all positions
get_active_positions - Get active positions
get_position_by_ticker - Get position by ticker
update_market_price - Update market price
recalculate_position - Recalculate position

Portfolio Tools

get_portfolio_summary - Complete portfolio summary
get_active_portfolio_summary - Active portfolio summary

🧪 Testing

API Testing

# Comprehensive API testing
./scripts/test-api.sh

# Quick functionality test
./scripts/quick-test.sh

# Populate sample data
./scripts/sample-data.sh

MCP Testing

# Test MCP server
./scripts/test-mcp.sh

# Interactive MCP client
python3 ./start_mcp_server.py --mode interactive

# Automated MCP testing
python3 ./start_mcp_server.py --mode test

Development Testing

# Run unit tests
./gradlew test

# Run with test coverage
./gradlew test jacocoTestReport

# Integration testing
./gradlew integrationTest

📊 Example Usage

REST API Examples

# Create a transaction
curl -X POST http://localhost:8080/api/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL",
    "transactionType": "BUY",
    "quantity": 10,
    "price": 150.00,
    "currency": "USD",
    "transactionDate": "2024-01-15"
  }'

# Get portfolio summary
curl http://localhost:8080/api/portfolio/summary/active

# Update market price
curl -X PUT http://localhost:8080/api/positions/ticker/AAPL/price \
  -H "Content-Type: application/json" \
  -d '{"price": 175.50}'

MCP Examples

# Using the Python MCP client
async with PortfolioMcpClient() as client:
    # Create transaction
    result = await client.call_tool('create_transaction', {
        "ticker": "AAPL",
        "transactionType": "BUY",
        "quantity": 10,
        "price": 150.00,
        "currency": "USD",
        "transactionDate": "2024-01-15"
    })
    
    # Get portfolio summary
    summary = await client.call_tool('get_portfolio_summary', {})

🔧 Configuration

Database Configuration

# PostgreSQL Configuration
quarkus.datasource.db-kind=postgresql
quarkus.datasource.reactive.url=postgresql://localhost:5432/portfolio_db
quarkus.datasource.username=portfolio_user
quarkus.datasource.password=secure_password

# Hibernate Configuration
quarkus.hibernate-orm.database.generation=validate
quarkus.hibernate-orm.sql-load-script=no-file

Server Configuration

# HTTP Server
quarkus.http.port=8080
quarkus.http.host=0.0.0.0

# Development
quarkus.live-reload.instrumentation=true
quarkus.dev.console.enable=true

🚀 Deployment

Docker Deployment

# Build Docker image
./gradlew build -Dquarkus.package.type=native-sources
docker build -f src/main/docker/Dockerfile.native -t portfolio-management .

# Run with docker-compose
docker-compose up -d

🤝 Development

Adding New Features

Domain Layer: Add new entities/value objects
Application Layer: Create use cases
Infrastructure Layer: Implement adapters
Interface Layer: Add REST endpoints and/or MCP tools

Code Style

Follow Java naming conventions
Use reactive patterns (Uni/Multi)
Maintain clean architecture boundaries
Write comprehensive tests

📚 Documentation

API Documentation: Available at /q/swagger-ui when running
Health Checks: Available at /q/health
Metrics: Available at /q/metrics
MCP Tools: Available at /mcp/tools

🛡️ Security Features

✅ Input Validation: Bean validation on all DTOs
✅ SQL Injection Protection: Parameterized queries
✅ CORS Configuration: Configurable cross-origin policies
✅ Error Handling: Consistent error responses

🔮 Roadmap

Authentication & Authorization
Event Sourcing for audit trails
Caching Layer with Redis
Microservices Split for event sourcing transactions service -> portfolio service (build position async)
Build a BFF Split MCP and REST API into different microservices

Built with ❤️ using Quarkus and Clean Architecture principles

Name		Name	Last commit message	Last commit date
Latest commit History 21 Commits
gradle		gradle
src		src
.gitignore		.gitignore
DOCKER.md		DOCKER.md
Dockerfile		Dockerfile
Dockerfile.jvm		Dockerfile.jvm
Procfile		Procfile
README.md		README.md
build.gradle		build.gradle
docker-compose.yml		docker-compose.yml
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
lombok.config		lombok.config
railway.toml		railway.toml
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

Transactions API

🏗️ Architecture Overview

🚀 Features

💼 Portfolio Management

🔄 Reactive Architecture

🌐 Multiple Interfaces

🗄️ Data Management

🛠️ Tech Stack

📦 Project Structure

🚀 Quick Start

Prerequisites

1. Database Setup

2. Application Configuration

3. Run the Application

4. Verify Installation

📡 API Documentation

🌐 REST API Endpoints

Transactions (/api/transactions)

Positions (/api/positions)

Portfolio (/api/portfolio)

🤖 MCP Server Tools

Transaction Tools

Position Tools

Portfolio Tools

🧪 Testing

API Testing

MCP Testing

Development Testing

📊 Example Usage

REST API Examples

MCP Examples

🔧 Configuration

Database Configuration

Server Configuration

🚀 Deployment

Docker Deployment

🤝 Development

Adding New Features

Code Style

📚 Documentation

🛡️ Security Features

🔮 Roadmap

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Transactions (`/api/transactions`)

Positions (`/api/positions`)

Portfolio (`/api/portfolio`)

Packages