Ledn Backend Challenge - Local Setup Guide

Quick Start

Prerequisites

• Node.js 22.15.0 or higher
• Docker and Docker Compose
• Git

One-Command Setup

git clone https://github.com/alanoteles/ledn-api.git
cd ledn-api
npm run setup:dev

This will:

1. Install dependencies
2. Start PostgreSQL with Docker
3. Run database migrations
4. Seed the database with development data
5. Start the API server

Access the Application

• API: http://localhost:3000/api/v1/accounts
• Documentation: http://localhost:3000/api-docs
• Health Check: http://localhost:3000

Manual Setup (Alternative)

1. Clone and Install

git clone https://github.com/alanoteles/ledn-api.git
cd ledn-api
npm install

2. Environment Configuration

cp .env.example .env
# Edit .env if needed - defaults should work for local development

3. Database Setup

# Start PostgreSQL
npm run docker:up

# Wait for database to be ready (about 10 seconds)
sleep 10

# Run migrations
npm run db:migrate

# Seed with development data (small dataset)
npm run db:seed:dev

4. Start the Application

# Development mode
npm run dev

# Or production build
npm run build
npm run start

Available Scripts

Development

• npm run dev - Start in development mode with hot reload
• npm run build - Build TypeScript to JavaScript
• npm run start - Start production build

Database

• npm run docker:up - Start PostgreSQL container
• npm run docker:down - Stop containers
• npm run db:migrate - Run database migrations
• npm run db:seed:dev - Seed with development data (~10k records)
• npm run db:seed - Seed with production data (~95k records)
• npm run db:reset - Reset database (careful!)

Testing

• npm run test - Run all tests
• npm run test:unit - Run unit tests only
• npm run test:integration - Run integration tests
• npm run test:coverage - Run tests with coverage

Quality

• npm run lint - Check code style
• npm run format - Format code with Prettier
• npm run typecheck - TypeScript type checking

Complete Setup

• npm run setup:dev - Full development setup (database + seed + start)
• npm run setup:test - Setup for testing environment

Database Seeding Options

Development Data (Recommended for testing)

npm run db:seed:dev

• ~5,000 accounts
• ~10,000 transactions
• Faster processing (~30 seconds)

Production Data (Full dataset)

npm run db:seed

• ~22,000 accounts
• ~95,000 transactions
• Processing time (~5-10 minutes)

API Testing

Health Check

curl http://localhost:3000

List Accounts

curl http://localhost:3000/api/v1/accounts

Create Account

curl -X POST http://localhost:3000/api/v1/accounts \
  -H "Content-Type: application/json" \
  -d '{"userEmail": "test@example.com", "initialBalance": 100}'

Make Deposit

curl -X POST http://localhost:3000/api/v1/accounts/test@example.com/deposit \
  -H "Content-Type: application/json" \
  -d '{"amount": 50}'

Docker Deployment (Optional)

Build and Run

npm run docker:build
npm run docker:run

Full Stack with Monitoring

docker-compose -f monitoring/docker-compose.monitoring.yml up -d

Access:

• API: http://localhost:3000
• Grafana: http://localhost:3001 (admin/admin123)
• Prometheus: http://localhost:9090

Troubleshooting

Database Connection Issues

# Check if PostgreSQL is running
docker ps | grep postgres

# Reset database if corrupted
npm run docker:down
npm run docker:up
sleep 10
npm run db:migrate

Port Conflicts

If port 3000 or 5432 are in use:

# Stop existing services
npx kill-port 3000
npx kill-port 5432

# Or change ports in .env file

TypeScript Compilation Errors

# Clean and rebuild
npm run clean
npm install
npm run build

Project Structure

src/
├── config/          # Configuration files
├── controllers/     # HTTP request handlers  
├── middleware/      # Express middleware
├── repositories/    # Data access layer
├── routes/         # API route definitions
├── services/       # Business logic
├── types/          # TypeScript type definitions
└── utils/          # Utility functions

tests/              # Test files
data/              # Seed data files
monitoring/        # Monitoring configuration

Production Deployment

The application is also deployed and accessible at:

• Live API: https://ledn-api.alanoteles.com/api/v1/accounts
• Documentation: https://ledn-api.alanoteles.com/api-docs/
• Monitoring: https://ledn-api.alanoteles.com/grafana/