Auth Service - NestJS + AWS Lambda + Terraform

Modern authentication microservice built with Node.js, NestJS, AWS Lambda, and Terraform.

---

Overview

This project implements a serverless authentication microservice leveraging AWS Lambda for scalability and cost efficiency.
It is built with NestJS, following clean architecture principles, and uses Terraform to fully manage AWS infrastructure as code.

Key Features

• API Gateway + Lambda: Real-time synchronous responses.
• SQS: Asynchronous command handling through message queues.
• EventBridge: Event publishing for decoupled integrations with other services.
• Secrets Manager: Secure storage for environment variables and sensitive credentials.
• CI/CD with GitHub Actions: Automatic deployment on every commit to main.
• Docker-based builds for efficient packaging and deployment to AWS Lambda.

---

Architecture

The system is built with a serverless and event-driven architecture using AWS services for both synchronous and asynchronous workflows:

• Clients:
  Applications or external services interacting with the system by sending requests.

• API Gateway:
  Routes incoming requests to the Lambda function.

  • Synchronous calls: Handled directly by Lambda, returning an immediate response.
  • Asynchronous calls: Commands are sent to SQS for background processing.

• Lambda (NestJS):

  • Handles synchronous requests coming from API Gateway.
  • Publishes messages to SQS for asynchronous workflows.
  • Publishes events to EventBridge for decoupled integrations.

• SQS (Simple Queue Service):
  Reliable, scalable queue for background job processing.

• EventBridge:
  Used to broadcast domain events to external services without tight coupling.

This approach ensures the system is scalable, reliable, and cost-efficient, with a clear separation between real-time and background processing.

---

Repository Structure

Repository Structure

.
├── app/                # Microservice code (NestJS)
│   ├── src/            # Application source code
│
├── infra/              # Main AWS infrastructure (Terraform)
│   ├── main.tf         # Core AWS resources (API Gateway, Lambda, SQS, EventBridge, etc.)
│   ├── variables.tf    # Global variables
│   └── backend.tf      # Remote backend configuration (S3 + DynamoDB)
│
├── infra-bootstrap/    # Initial setup for Terraform backend
│   ├── main.tf
│   └── variables.tf
│
└── bootstrap/          # Helper scripts for initialization

CI/CD Workflow

The deployment pipeline is fully automated via GitHub Actions:

1. Commit to main branch triggers the workflow.
2. Application build
   • Packages code from app/ into a Docker container.
   • Generates final build artifact.
3. Upload to S3 and Lambda
   • Terraform updates the Lambda function.
   • Secrets Manager injects environment variables.
4. Terraform Apply
   • Infrastructure is provisioned or updated automatically.
5. Final deployment
   • Lambda updated and API ready to serve traffic.

The entire deployment pipeline is fully automated — no manual steps required.

---

Initial Setup

1. Bootstrap the Terraform Backend

Creates foundational AWS resources for Terraform:

• S3 bucket to store state (tfstate).
• DynamoDB table for state locking.
• GitHub OIDC role for CI/CD deployments.

cd infra-bootstrap
terraform init
terraform apply -auto-approve

2. Configure Terraform Backend

Edit infra/backend.tf with the outputs from the bootstrap step:

terraform {
  backend "s3" {
    bucket         = "tfstate-bucket-name"
    key            = "infra/terraform.tfstate"
    region         = "sa-east-1"
    dynamodb_table = "lock-table-name"
    encrypt        = true
  }
}

3. Set Up GitHub Secrets

Go to:

GitHub → Settings → Secrets and variables → Actions

Add the following secrets:

Secret Name	Description
OIDC_ROLE_ARN	ARN of the OIDC role created in bootstrap.
ARTIFACTS_BUCKET	S3 bucket for application deployment artifacts.
DOTENV_SECRET_ARN	Secrets Manager ARN containing your .env JSON.

Example JSON for Secrets Manager:

{
  "DATABASE_URI": "mongodb+srv://user:[email protected]",
  "SECRET_TOKEN_JWT": "supersecret",
  "NODE_ENV": "production"
}

cd app
npm install
npm run start:dev

4. Run Locally (Optional)

Start the app locally:

cd app
npm install
npm run start:dev

Technologies Used

Backend:

• NestJS
• Node.js
• TypeScript

AWS Services:

• Lambda
• API Gateway
• SQS
• EventBridge
• Secrets Manager
• S3 (artifacts storage)
• DynamoDB (Terraform state lock)

Infrastructure:

• Terraform
• GitHub Actions (CI/CD)
• Docker

---

Deployment Flow

# Local
cd infra
terraform init
terraform plan
terraform apply

# CI/CD (GitHub Actions)
git add .
git commit -m "feat: new authentication feature"
git push origin main

GitHub Actions Workflow

The GitHub Actions workflow will:

1. Build and package the application.
2. Upload the Docker image to S3.
3. Run terraform apply to update infrastructure.
4. Update the Lambda function and all related AWS resources automatically.

---

License

This project is licensed under the MIT License.

---

Summary

This project demonstrates:

• A modern serverless architecture using AWS Lambda, SQS, and EventBridge.
• Fully automated infrastructure as code with Terraform.
• End-to-end CI/CD pipeline, from commit to production deployment.
• Clean, scalable code with NestJS, perfect for portfolio showcasing.

A practical example of designing and running a production-ready microservice using cloud-native patterns and professional practices.