Dromanis Finora - Transactions Service

A professional-grade serverless microservice for managing financial transactions in the Dromanis Finora portfolio management platform. Built with AWS Lambda, TypeScript, and featuring comprehensive authentication, CORS support, and robust error handling.

🏗️ Architecture

This service implements a clean architecture pattern with:

• AWS Lambda Functions: Serverless compute for scalable API endpoints
• Domain Services: Business logic layer for transaction management
• Database Layer: MySQL integration for persistent storage
• Authentication: JWT-based user authentication
• CORS Support: Cross-origin resource sharing for web applications

📋 Features

Transaction Management

• Trade Transactions: Handle stock/securities buy/sell operations
• Cash Transactions: Manage deposits, withdrawals, dividends, and fees
• Portfolio Integration: Link transactions to specific user portfolios
• Broker Integration: Track transactions across multiple brokers

Technical Features

• 🔐 JWT Authentication: Secure user authentication with token validation
• 🌐 CORS Support: Configurable cross-origin resource sharing
• 📊 Comprehensive Logging: Structured logging with correlation IDs
• 🧪 Full Test Coverage: Unit tests for all components
• 🚀 CI/CD Ready: Automated testing with Husky hooks
• 📦 AWS SAM: Infrastructure as Code with SAM templates

🛠️ Technology Stack

• Runtime: Node.js 22.x
• Language: TypeScript 5.0+
• Framework: AWS Lambda + API Gateway
• Database: MySQL with connection pooling
• Testing: Jest with mocking
• Build: TypeScript compiler + AWS SAM
• Deployment: AWS SAM CLI

📚 API Documentation

Authentication

All endpoints (except version endpoints) require JWT authentication:

• Header: Authorization: Bearer <jwt_token>
• Token Payload: Must contain user ID in id field

Trade Transactions Service

Base URL

/api/transactions/trades

Endpoints

1. Get Service Version (Public)

GET /api/transactions/trades/version

Response:

{
  "version": "3.0.1"
}

2. Get Trade Transactions (Authenticated)

GET /api/transactions/trades
Authorization: Bearer <jwt_token>

Response:

[
  {
    "id": "trade-uuid",
    "userId": "user-uuid",
    "instrumentId": "instrument-uuid",
    "direction": "BUY",
    "quantity": 100,
    "price": 150.25,
    "exchangeRateToPortfolioCurrency": 1.0,
    "transactionDateTime": "2024-01-15T10:30:00Z",
    "transactionFee": 9.99,
    "portfolioId": "portfolio-uuid",
    "brokerId": "broker-uuid",
    "brokerTransactionId": "broker-ref-123",
    "notes": "Initial purchase"
  }
]

3. Create/Update Trade Transaction (Authenticated)

POST /api/transactions/trades
Authorization: Bearer <jwt_token>
Content-Type: application/json

Request Body:

{
  "id": "trade-uuid", // Optional for updates
  "instrumentId": "instrument-uuid",
  "direction": "BUY", // or "SELL"
  "quantity": 100,
  "price": 150.25,
  "exchangeRateToPortfolioCurrency": 1.0,
  "transactionDateTime": "2024-01-15T10:30:00Z",
  "transactionFee": 9.99,
  "portfolioId": "portfolio-uuid",
  "brokerId": "broker-uuid",
  "brokerTransactionId": "broker-ref-123",
  "notes": "Initial purchase"
}

Response:

{
  "id": "trade-uuid",
  "userId": "user-uuid",
  // ... same structure as request
}

Cash Transactions Service

Base URL

/api/transactions/cash

Endpoints

1. Get Service Version (Public)

GET /api/transactions/cash/version

Response:

{
  "version": "3.0.1"
}

2. Get Cash Transactions (Authenticated)

GET /api/transactions/cash
Authorization: Bearer <jwt_token>

Response:

[
  {
    "id": "cash-uuid",
    "userId": "user-uuid",
    "portfolioId": "portfolio-uuid",
    "type": "DEPOSIT",
    "direction": "CREDIT",
    "amount": 1000.00,
    "transactionDateTime": "2024-01-15T09:00:00Z",
    "notes": "Initial deposit"
  }
]

3. Create/Update Cash Transaction (Authenticated)

POST /api/transactions/cash
Authorization: Bearer <jwt_token>
Content-Type: application/json

Request Body:

{
  "id": "cash-uuid", // Optional for updates
  "portfolioId": "portfolio-uuid",
  "type": "DEPOSIT", // DEPOSIT, WITHDRAWAL, DIVIDEND, FEE, etc.
  "direction": "CREDIT", // CREDIT or DEBIT
  "amount": 1000.00,
  "transactionDateTime": "2024-01-15T09:00:00Z",
  "notes": "Initial deposit"
}

Response:

{
  "id": "cash-uuid",
  "userId": "user-uuid",
  // ... same structure as request
}

Error Responses

All endpoints return consistent error responses:

{
  "error": "Descriptive error message"
}

Common HTTP Status Codes:

• 200: Success
• 400: Bad Request (validation errors)
• 401: Unauthorized (authentication failed)
• 405: Method Not Allowed
• 500: Internal Server Error

🚀 Getting Started

Prerequisites

• Node.js 22.x or higher
• AWS CLI configured
• AWS SAM CLI installed
• MySQL database instance

Installation

1. Clone the repository:

   git clone <repository-url>
   cd dromanis.finora.functions.transactions

2. Install dependencies:

   npm install

3. Create environment configuration:

   cp .env.example .env.local.json
   # Edit .env.local.json with your configuration

Local Development

1. Build the project:

   npm run build

2. Start local development server:

   npm start

   Server will run on http://localhost:3003

3. Run in debug mode:

   npm run debug

   Debug server runs on port 9229

Testing

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

🚀 Deployment

AWS SAM Deployment

1. Build for deployment:

   npm run build

2. Deploy (guided first time):

   npm run deploy

3. Deploy (subsequent deployments):

   sam deploy

Environment Variables

Configure the following environment variables in AWS Lambda:

| Variable | Description | |----------|-------------| | VERSION | Application version | | JWT_SECRET | Secret key for JWT validation | | DB_HOST | Database host | | DB_PORT | Database port | | DB_USER | Database username | | DB_PASSWORD | Database password | | DB_NAME | Database name | | DB_SSL | Enable SSL for database | | DB_CONNECTION_LIMIT | Max database connections | | DB_ACQUIRE_TIMEOUT | Connection acquisition timeout | | DB_TIMEOUT | Query timeout | | LOG_LEVEL | Logging level | | LOG_TIMESTAMP | Enable timestamps in logs |

Service URLs

| Variable | Description | |----------|-------------| | SYSTEM_SERVICE_BASE_URL | Base URL for system services | | USER_SERVICE_BASE_URL | Base URL for user services | | PORTFOLIO_SERVICE_BASE_URL | Base URL for portfolio services | | TRANSACTION_SERVICE_BASE_URL | Base URL for transaction services | | ANALYTICAL_SERVICE_BASE_URL | Base URL for analytical services |

🧪 Testing Strategy

Unit Tests

• Domain Services: Test business logic with mocked dependencies
• Lambda Functions: Test HTTP handling and authentication
• Error Scenarios: Comprehensive error handling coverage

Test Structure

src/__tests__/
├── domain/
│   ├── CashTransactionService.test.ts
│   └── TradeTransactionService.test.ts
└── functions/
    ├── cashTransactionsFunction.test.ts
    └── tradeTransactionsFunction.test.ts

Git Hooks

• Pre-commit: Runs linting and tests
• Pre-push: Ensures all tests pass before push

📁 Project Structure

dromanis.finora.functions.transactions/
├── src/
│   ├── domain/                     # Business logic layer
│   │   ├── CashTransactionService.ts
│   │   └── TradeTransactionService.ts
│   ├── functions/                  # Lambda function handlers
│   │   ├── cashTransactionsFunction.ts
│   │   └── tradeTransactionsFunction.ts
│   ├── __tests__/                  # Test files
│   └── index.ts                    # Main entry point
├── template.yaml                   # AWS SAM template
├── samconfig.toml                  # SAM configuration
├── package.json                    # Dependencies and scripts
├── tsconfig.json                   # TypeScript configuration
├── jest.config.js                  # Jest configuration
└── deploy.sh                       # Deployment script

🔧 Development Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript and build SAM | | npm start | Start local development server | | npm test | Run all tests | | npm run lint | Run ESLint | | npm run lint:fix | Fix ESLint issues | | npm run clean | Remove build artifacts | | npm run debug | Start debug server | | npm run deploy | Deploy with SAM guided mode |

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Make your changes
4. Run tests (npm test)
5. Commit your changes (git commit -am 'Add your feature')
6. Push to the branch (git push origin feature/your-feature)
7. Create a Pull Request

Code Standards

• Follow TypeScript best practices
• Maintain test coverage above 80%
• Use conventional commit messages
• Ensure all linting passes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For support and questions:

• Create an issue in the repository
• Contact the development team
• Check the documentation wiki

Dromanis Finora Transactions Service - Professional portfolio management platform