Platform Interview

A monorepo containing a simple REST API service deployed with Docker and managed via Terraform infrastructure. The project demonstrates a complete local development setup using LocalStack for AWS service emulation.

Note: This project is designed for macOS and may or may not work on other operating systems.

LocalStack allows us to emulate AWS services locally. The community edition is quite limited and some services are not enabled or they are just stubs that don't implement the full functionality.

Overview

This project consists of:

• Hello World API: A TypeScript/Express.js REST API service
• Infrastructure: Terraform configuration for AWS API Gateway (deployed to LocalStack)
• Docker Compose: Local development environment with LocalStack, PostgreSQL, and the API service

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js >= 20.0.0
• npm >= 10.0.0
• Docker and Docker Compose (for running services locally)
• Terraform >= 1.0 (for infrastructure provisioning)

Node.js Version Management

This project requires Node.js >= 20.0.0. We strongly recommend using nvm (Node Version Manager) for managing Node.js versions.

This project includes a .nvmrc file that specifies the required Node.js version. When you navigate to the project directory, you can use nvm use to automatically switch to the correct version.

Installation with nvm

# Install nvm using Homebrew
brew install nvm

# Reload your shell configuration
source ~/.zshrc

# Navigate to the project directory and use the version from .nvmrc
cd /path/to/interview-platform-eng
nvm install  # Installs the version specified in .nvmrc
nvm use      # Switches to the version specified in .nvmrc

# Verify installation
node --version
npm --version

Terraform Version Management

This project uses Terraform v1.12.2. We strongly recommend using tfenv for managing Terraform versions.

This project includes a .terraform-version file that specifies the required Terraform version. When you navigate to the project directory, tfenv will automatically detect and use the correct version.

Installation with tfenv

brew install tfenv

# Navigate to the project directory
cd /path/to/interview-platform-eng

# Install the version specified in .terraform-version
tfenv install

# tfenv will automatically use the version from .terraform-version
# Or manually switch with:
tfenv use

# Verify installation
terraform version

Quick Start

1. Install dependencies:

   npm install

2. Start all services:

   npm start

   This command will:

   • Build the API Docker image
   • Start Docker Compose services (LocalStack, PostgreSQL, API)
   • Wait for services to be healthy
   • Apply Terraform configuration to create API Gateway in LocalStack

3. Access the services:

   • API Gateway URL: Check the Terraform output after npm start completes
   • Direct API: http://localhost:3000
   • LocalStack Health: http://localhost:4566/_localstack/health
   • PostgreSQL: localhost:5433

Available Scripts

• npm install - Install all dependencies and build the API
• npm start - Start all services (Docker + Terraform)
• npm run start:docker - Start only Docker Compose services
• npm run start:infrastructure - Apply Terraform configuration only
• npm run build - Build the API and start all services

Project Structure

.
├── projects/
│   ├── hello-world-api/          # Express.js API service
│   │   ├── src/                  # TypeScript source code
│   │   ├── tests/                # Test suites
│   │   └── Dockerfile            # API container definition
│   └── infrastructure/           # Terraform configuration
│       ├── apigateway.tf         # API Gateway resources
│       ├── main.tf               # Provider configuration
│       ├── variables.tf          # Variable definitions
│       └── outputs.tf            # Output values
├── scripts/
│   └── build-api.sh              # API build script
├── docker-compose.yml            # Local development services
└── package.json                  # Root package configuration

Services

Hello World API

A REST API service providing:

• GET / - Returns "hello world"
• GET /health - Health check endpoint

LocalStack

AWS service emulator running on port 4566. Provides local AWS services including:

• API Gateway
• Lambda
• S3
• EC2, IAM, CloudWatch, and more

Health Check: http://localhost:4566/_localstack/health

PostgreSQL

Database service running on port 5433.

Connection Details:

• Host: localhost
• Port: 5433
• Database: hello_world_db
• User: postgres
• Password: postgres

API Gateway

After running npm start, Terraform will create an API Gateway in LocalStack that proxies requests to the Hello World API. The API Gateway URL will be displayed in the Terraform output.

Format: http://localhost:4566/restapis/{api-id}/v1/_user_request_

Development Workflow

1. Make changes to the API:

   • Edit files in projects/hello-world-api/src/
   • Rebuild: npm run build

2. Update infrastructure:

   • Modify Terraform files in projects/infrastructure/
   • Apply changes: npm run start:infrastructure

3. View logs:

   docker compose logs -f hello-world-api
   docker compose logs -f localstack

4. Stop services:

   docker compose down