TechFin Backend API

A TypeScript-based backend API for a financial technology application that provides user authentication, transaction management, and advanced financial data operations.

🚀 Features

• User Authentication: Secure registration, login, and JWT-based authentication
• Transaction Management: Create, read, update, and delete financial transactions
• Advanced Filtering: Search transactions by payee, category, date range, and more
• Pagination: Efficient data retrieval with pagination support
• Security: Password hashing, JWT tokens, CORS protection, and Helmet security
• Database: SQLite with Knex.js for migrations and query building
• Health Monitoring: Built-in health check endpoints
• Graceful Shutdown: Proper cleanup and database connection management

🛠️ Technology Stack

• Runtime: Node.js with TypeScript
• Framework: Express.js
• Database: SQLite with Knex.js
• Authentication: JWT + bcrypt
• Security: Helmet, CORS
• Development: ts-node, ts-node-dev
• File Processing: Multer, CSV parser

📦 Installation

1. Clone the repository

   git clone <repository-url>
   cd TechFin

2. Install dependencies

   npm install

3. Set up environment variables Create a .env file in the root directory:

   NODE_ENV=development
   PORT=3000
   JWT_SECRET=your-secret-key
   JWT_REFRESH_SECRET=your-refresh-secret-key
   ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001

4. Run database migrations

   npm run migrate

🏃‍♂️ Running the Application

Development Mode

npm run dev

Development with Auto-reload

npm run dev:watch

Production Build

npm run build
npm start

Database Operations

# Run migrations
npm run migrate

# Rollback migrations
npm run migrate:rollback

# Create new migration
npm run migrate:make <migration-name>

📚 API Documentation

Base URL

http://localhost:3000

Authentication Endpoints

Register User

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

cURL Example:

curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

Login

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

cURL Example:

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securepassword"
  }'

Response:

{
  "accessToken": "jwt-access-token",
  "refreshToken": "jwt-refresh-token"
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "userId": 1,
  "refreshToken": "jwt-refresh-token"
}

cURL Example:

curl -X POST http://localhost:3000/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "refreshToken": "jwt-refresh-token"
  }'

Transaction Endpoints

🔒 Note: All transaction endpoints require authentication. Include the JWT token in the Authorization header:

Authorization: Bearer <access-token>

How to get access token:

1. First register a user using /auth/register
2. Then login using /auth/login to get the access token
3. Replace YOUR_ACCESS_TOKEN in the curl examples below with your actual token

Create Transaction

POST /api/create-transaction
Content-Type: application/json

{
  "payee": "Amazon",
  "amount": 49.99,
  "category": "shopping",
  "transaction_date": "2025-01-15T10:30:00Z",
  "note": "Monthly subscription"
}

cURL Example:

curl -X POST http://localhost:3000/api/create-transaction \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "payee": "Amazon",
    "amount": 49.99,
    "category": "shopping",
    "transaction_date": "2025-01-15T10:30:00Z",
    "note": "Monthly subscription"
  }'

Get Transactions (with filtering and pagination)

GET /api/transactions?page=1&pageSize=10&search=amazon&category=shopping&start=2025-01-01&end=2025-01-31

Query Parameters:

• page (optional): Page number (default: 1)
• pageSize (optional): Items per page (default: 10)
• search (optional): Search by payee name
• category (optional): Filter by category
• start (optional): Start date (YYYY-MM-DD)
• end (optional): End date (YYYY-MM-DD)

cURL Examples:

# Get all transactions with pagination
curl -X GET "http://localhost:3000/api/transactions?page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Search transactions by payee
curl -X GET "http://localhost:3000/api/transactions?search=amazon&page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by category and date range
curl -X GET "http://localhost:3000/api/transactions?category=shopping&start=2025-01-01&end=2025-01-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Transactions by Date

GET /api/transactions/by-date?year=2025&month=1&day=15

Query Parameters:

• year (required): Year
• month (optional): Month (1-12)
• day (optional): Day (1-31)

cURL Examples:

# Get transactions for a specific day
curl -X GET "http://localhost:3000/api/transactions/by-date?year=2025&month=1&day=15" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get transactions for a specific month
curl -X GET "http://localhost:3000/api/transactions/by-date?year=2025&month=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get transactions for a specific year
curl -X GET "http://localhost:3000/api/transactions/by-date?year=2025" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Recent Transactions

GET /api/transactions/last?days=30

cURL Example:

# Get transactions from last 30 days
curl -X GET "http://localhost:3000/api/transactions/last?days=30" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Get transactions from last 7 days
curl -X GET "http://localhost:3000/api/transactions/last?days=7" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Transaction

PUT /api/:id
Content-Type: application/json

{
  "payee": "Updated Payee",
  "amount": 59.99,
  "category": "updated-category",
  "transaction_date": "2025-01-16T10:30:00Z",
  "note": "Updated note"
}

cURL Example:

curl -X PUT http://localhost:3000/api/123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "payee": "Updated Payee",
    "amount": 59.99,
    "category": "updated-category",
    "transaction_date": "2025-01-16T10:30:00Z",
    "note": "Updated note"
  }'

Delete Transaction

DELETE /api/:id

cURL Example:

curl -X DELETE http://localhost:3000/api/123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Health Check Endpoints

Basic Health Check

GET /health

cURL Example:

curl -X GET http://localhost:3000/health

Detailed Health Check

GET /health/detailed

cURL Example:

curl -X GET http://localhost:3000/health/detailed

🔄 Example Workflow

Here's a complete example workflow using curl commands:

# 1. Register a new user
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "password": "securepassword123"}'

# 2. Login to get access token
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "password": "securepassword123"}'

# Save the accessToken from the response and use it in subsequent requests

# 3. Create a transaction
curl -X POST http://localhost:3000/api/create-transaction \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "payee": "Starbucks",
    "amount": 15.50,
    "category": "food",
    "transaction_date": "2025-01-15T08:30:00Z",
    "note": "Morning coffee"
  }'

# 4. Get all transactions
curl -X GET "http://localhost:3000/api/transactions?page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 5. Search for specific transactions
curl -X GET "http://localhost:3000/api/transactions?search=starbucks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

📁 Project Structure

TechFin/
├── src/
│   ├── database/
│   │   ├── connection.ts          # Database connection setup
│   │   ├── migrations/            # Database migration files
│   │   └── sqlLite.ts            # SQLite configuration
│   ├── middleware/
│   │   ├── authMiddleware.ts      # JWT authentication middleware
│   │   ├── errorHandler.ts       # Global error handling
│   │   └── notFoundHandler.ts    # 404 error handler
│   ├── repo/
│   │   ├── baseRepository.ts     # Base repository pattern
│   │   ├── tokenRepo.ts          # Token repository
│   │   ├── transactionRepo.ts    # Transaction repository
│   │   └── userRepo.ts           # User repository
│   ├── routes/
│   │   ├── api.ts                # Transaction API routes
│   │   ├── auth.ts               # Authentication routes
│   │   └── health.ts             # Health check routes
│   ├── services/
│   │   ├── authService.ts        # Authentication business logic
│   │   └── transactionService.ts # Transaction business logic
│   ├── types/
│   │   ├── express.d.ts          # Express type extensions
│   │   └── index.ts              # Type definitions
│   ├── utils/
│   │   ├── hashPassword.ts       # Password hashing utilities
│   │   ├── jwt.ts                # JWT utilities
│   │   ├── logger.ts             # Logging utilities
│   │   ├── refreshToken.ts       # Refresh token utilities
│   │   └── validation.ts         # Input validation
│   └── index.ts                  # Application entry point
├── knexfile.ts                   # Knex configuration
├── package.json                  # Dependencies and scripts
└── tsconfig.json                 # TypeScript configuration

🔧 Development

Adding New Migrations

npm run migrate:make create_new_table

Database Schema

The application uses the following main tables:

• users - User accounts with authentication
• user_tokens - JWT refresh tokens
• transactions - Financial transaction records

Security Features

• Password hashing with bcrypt
• JWT access and refresh tokens
• CORS protection
• Helmet security headers
• Input validation and sanitization
• Graceful error handling

🚀 Deployment

1. Build the application

   npm run build

2. Set production environment variables

   NODE_ENV=production
   PORT=3000
   JWT_SECRET=your-production-secret
   JWT_REFRESH_SECRET=your-production-refresh-secret
   ALLOWED_ORIGINS=https://yourdomain.com

3. Run migrations

   npm run migrate

4. Start the application

   npm start

📝 API Response Format

Success Response

{
  "message": "Success message",
  "data": { /* response data */ },
  "timestamp": "2025-01-15T10:30:00Z"
}

Error Response

{
  "message": "Error message",
  "error": "Error details",
  "timestamp": "2025-01-15T10:30:00Z"
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Commit your changes: git commit -am 'Add new feature'
4. Push to the branch: git push origin feature/new-feature
5. Submit a pull request

📄 License

This project is licensed under the ISC License.

🐛 Troubleshooting

Common Issues

1. Database Connection Error

   • Ensure SQLite database file permissions are correct
   • Check if migrations have been run

2. Authentication Errors

   • Verify JWT_SECRET is set in environment variables
   • Check if access token is properly included in requests

3. Port Already in Use

   • Change the PORT in your .env file
   • Kill processes using the port: lsof -ti:3000 | xargs kill

Logs

The application uses Morgan for request logging in development mode. Check console output for detailed error messages.