🏦 Transaction Aggregation API

A production-grade RESTful API that aggregates customer financial transaction data from multiple sources, automatically categorizes transactions, and provides extensive analytics capabilities.

🛠️ Technology Stack

Component	Technology
Runtime	Node.js 20
Framework	Express.js 4
Database	PostgreSQL 17
Testing	Jest + Supertest
Migration	db-migrate
Containerization	Docker + Docker Compose
HTTP Client	Axios

---

📦 Prerequisites

• Docker Desktop (Download)
• Git (Download)

---

🚀 Quick Start

Docker

# 1. Clone the repository
git clone https://github.com/heis-sn3/transacation-aggregation-api.git
cd transaction-aggregation-api


# 2. Start with Docker Compose
docker-compose up -d

# 3. Check health
curl http://localhost:3000/api/v1/health

# 4. Trigger initial sync
curl -X POST http://localhost:3000/api/v1/sync

📚 API Documentation

Base URL

http://localhost:3000/api/v1

Core Endpoints

Health & Status

GET  /health                  # Application health check
GET  /sync/status             # Data synchronization status
POST /sync                    # Trigger data sync

Transactions

GET  /transactions            # List all transactions (paginated)
GET  /transactions/:id        # Get single transaction
GET  /transactions/stats/summary  # Transaction statistics

Aggregations

GET  /aggregations/summary              # Financial overview
GET  /aggregations/by-category          # Category breakdown
GET  /aggregations/by-source            # Source comparison
GET  /aggregations/by-type              # Income vs Expense
GET  /aggregations/by-month             # Monthly trends
GET  /aggregations/top-merchants        # Top spending merchants
GET  /aggregations/category-trends/:cat # Category trends over time
GET  /aggregations/spending-patterns    # Day-of-week patterns

Example Requests

# Get all transactions
curl http://localhost:3000/api/v1/transactions

# Get financial summary
curl http://localhost:3000/api/v1/aggregations/summary

# Get transactions with pagination
curl "http://localhost:3000/api/v1/transactions?limit=10&offset=0"

# Get category breakdown for date range
curl "http://localhost:3000/api/v1/aggregations/by-category?startDate=2025-10-01&endDate=2025-10-31"

# Get top 5 merchants
curl "http://localhost:3000/api/v1/aggregations/top-merchants?limit=5"

---

🗄️ Database Migrations

Using db-migrate

# Run migrations (local)
cd backend
npm run migrate:up

# Rollback migrations
npm run migrate:down

# Check migration status
npm run migrate:status

🐳 Docker Deployment

Production Deployment

# Build and start
docker-compose up --build -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Remove volumes (WARNING: Deletes data)
docker-compose down -v

---

⚙️ Environment Variables

Required Variables

Variable	Description	Example
DB_NAME	Database name	transaction_db
DB_USER	Database user	bankapi
DB_PASSWORD	Database password	bankapi123
DB_HOST	Database host	localhost or postgres
DB_PORT	Database port	5433 (host) or 5432 (Docker)
BANK1_API_URL	Bank 1 API endpoint	https://68fbe73994ec960660277586.mockapi.io/api/transact/Transactions
BANK2_API_URL	Bank 2 API endpoint	https://mock.apidog.com/m1/1107889-1098360-default/transactions

Optional Variables

Variable	Description	Default
NODE_ENV	Environment	development
PORT	API port	3000
LOG_LEVEL	Logging level	info
DB_POOL_MIN	Min DB connections	2
DB_POOL_MAX	Max DB connections	10