Skip to content

Home

Jump to bottom
Luan Rezende edited this page Aug 18, 2025 · 5 revisions

Arithmetic Calculator Project

Build Status License Version AWS Lambda React TypeScript .NET Vite TailwindCSS MySQL GitHub Actions

Live Application

Live Demo

Serverless arithmetic calculator with real-time balance tracking, JWT authentication, and comprehensive operation history.

AWS Infrastructure Architecture

graph TB
    CF[CloudFront CDN]:::cdn --> S3[S3 Frontend]:::storage
    CF --> API[API Gateway]:::api
    API --> UL[User Lambda]:::lambda
    API --> OL[Operation Lambda]:::lambda
    UL --> RDS[(Aurora MySQL)]:::database
    OL --> RDS
    OL -.->|Invoke| UL
    
    subgraph VPC[" VPC Network "]
        UL
        OL
        RDS
    end
    
    classDef cdn fill:#FF9900,stroke:#000,stroke-width:2px,color:#fff
    classDef storage fill:#569A31,stroke:#000,stroke-width:2px,color:#fff
    classDef api fill:#FF4F8B,stroke:#000,stroke-width:2px,color:#fff
    classDef lambda fill:#FF9900,stroke:#000,stroke-width:2px,color:#fff
    classDef database fill:#4479A1,stroke:#000,stroke-width:2px,color:#fff
    style VPC fill:#232F3E,stroke:#FF9900,stroke-width:3px,color:#fff
Loading

📊 Tech Stack

Layer Technology Purpose
Frontend React 18.3 + TypeScript 5.6 + Vite 5.4 + TailwindCSS 3.4 Modern responsive SPA
Backend AWS Lambda (.NET 8) + Clean Architecture Serverless microservices
Database Aurora Serverless v2 MySQL (0.5-1.0 ACUs) Auto-scaling MySQL database
API Gateway AWS REST API (Regional) RESTful API endpoints
CDN CloudFront + S3 Origin Global content delivery
Security JWT + BCrypt + VPC + Security Groups Multi-layered security
CI/CD GitHub Actions Automated deployment pipeline
Monitoring CloudWatch Logs and metrics

Key Features

Operations Engine

  • Addition, Subtraction, Multiplication, Division
  • Square Root calculations
  • Random string generation (Random.org API)
  • Real-time cost calculation
  • Operation history with pagination
  • Soft delete functionality

Security & Authentication

  • JWT Bearer Authentication
  • BCrypt password hashing
  • VPC network isolation
  • Security Groups enforcement
  • CORS policy configuration
  • API Gateway integration

User Experience

  • Responsive design (mobile-first)
  • Dark/Light mode toggle
  • Real-time balance updates
  • Toast notifications
  • Search & filter operations
  • Charts visualization (ApexCharts)

Project Structure

Repository Purpose Tech Stack Build Status Version
Operation API Arithmetic operations & random strings .NET 8 + Entity Framework Core + MySQL Build Status Version
User API Authentication & user management .NET 8 + JWT + BCrypt.Net Build Status Version
Frontend Modern React SPA React 18.3 + TypeScript 5.6 + Vite 5.4 Build Status Version

🚀 Infrastructure Deployment

Prerequisites

  1. AWS Account with appropriate permissions
  2. AWS CLI configured
  3. GitHub Secrets configured for CI/CD

CloudFormation Stack Deployment

# Deploy infrastructure stack
aws cloudformation create-stack \
  --stack-name arithme-calc-infrastructure \
  --template-body file://cloudformation-infrastructure.yaml \
  --parameters \
    ParameterKey=DBMasterPassword,ParameterValue=YourSecurePassword123! \
    ParameterKey=JWTSecretKey,ParameterValue=your-super-secret-jwt-key-min-32-chars \
  --capabilities CAPABILITY_NAMED_IAM

# After Lambda functions are deployed, update stack to create permissions
aws cloudformation update-stack \
  --stack-name arithme-calc-infrastructure \
  --use-previous-template \
  --parameters \
    ParameterKey=CreateLambdaPermissions,ParameterValue=true \
    ParameterKey=DBMasterPassword,UsePreviousValue=true \
    ParameterKey=JWTSecretKey,UsePreviousValue=true \
  --capabilities CAPABILITY_NAMED_IAM

Lambda Functions Deployment

Lambda functions are deployed via GitHub Actions CI/CD pipeline:

# Operation API Lambda
Function Name: ArithmeticCalculatorOperationApi
Runtime: dotnet8
Handler: ArithmeticCalculatorOperationApi::ArithmeticCalculatorOperationApi.LambdaEntryPoint::FunctionHandlerAsync
Memory: 256 MB
Timeout: 30 seconds

# User API Lambda  
Function Name: ArithmeticCalculatorUserApi
Runtime: dotnet8
Handler: ArithmeticCalculatorUserApi::ArithmeticCalculatorUserApi.LambdaEntryPoint::FunctionHandlerAsync
Memory: 256 MB
Timeout: 30 seconds

⚙️ Environment Configuration

User API Environment Variables

MYSQL_CONNECTION_STRING=Server=<aurora-endpoint>;Database=calcdb;User=admin;Password=xxx;Port=3306
JWT_SECRET_KEY=your-super-secret-jwt-key-min-32-chars
PROMOTIONAL_AMOUNT=80

Operation API Environment Variables

MYSQL_CONNECTION_STRING=Server=<aurora-endpoint>;Database=calcdb;User=admin;Password=xxx;Port=3306
JWT_SECRET_KEY=your-super-secret-jwt-key-min-32-chars
USER_LAMBDA_BASE_ARN=arn:aws:lambda:us-east-1:<account>:function:ArithmeticCalculatorUserApi
USER_DEBIT_ENDPOINT=/v1/user/account/balance
USER_PROFILE_ENDPOINT=/v1/user/profile

Frontend Environment Variables

VITE_API_BASE_URL=https://<cloudfront-domain>/api

GitHub Actions Secrets Required

AWS_ACCESS_KEY_ID=<your-access-key>
AWS_SECRET_ACCESS_KEY=<your-secret-key>
S3_BUCKET_NAME=arithme-calc-frontend-<account-id>
CLOUDFRONT_DISTRIBUTION_ID=<distribution-id>
VITE_API_BASE_URL=https://<cloudfront-domain>/api

📚 API Documentation

Base URLs

Environment URL
Production https://<cloudfront-domain>/api
API Gateway Direct https://<api-id>.execute-api.us-east-1.amazonaws.com/dev/api
Local Development http://localhost:5000 (Operation) / http://localhost:5001 (User)

API Routes Structure

CloudFront: https://<cloudfront-domain>
├── /                           # Frontend (S3)
├── /api/                       # API Gateway
│   ├── /api/user/*            # User API Lambda
│   │   ├── /api/user/health
│   │   └── /api/user/...
│   ├── /api/auth/*            # User API Lambda (Auth endpoints)
│   │   ├── /api/auth/register
│   │   ├── /api/auth/login
│   │   └── /api/auth/...
│   └── /api/operation/*       # Operation API Lambda
│       ├── /api/operation/health
│       └── /api/operation/...

Health Check Endpoints

Endpoint Method Response
/api/user/health GET { "status": "healthy", "timestamp": "..." }
/api/operation/health GET { "status": "healthy", "timestamp": "..." }

Authentication Endpoints

Endpoint Method Payload Response
/api/auth/register POST { "email": "[email protected]", "password": "Pass123!" } User + JWT tokens
/api/auth/login POST { "email": "[email protected]", "password": "Pass123!" } JWT + refresh tokens
/api/auth/refresh POST { "refreshToken": "..." } New JWT token
/api/auth/logout POST { "refreshToken": "..." } Success message

User Management Endpoints

Endpoint Method Payload Response
/api/user/profile GET - User info + balance
/api/user/account/balance POST { "amount": 5.0 } Updated balance (deduction)
/api/user/account/balance PUT { "newBalance": 100.0 } Set balance (admin)

Operations Endpoints

Endpoint Method Parameters Response
/api/operation/types GET - List of operations with costs
/api/operation/records GET ?page=1&size=10&search=add Paginated history
/api/operation/records POST { "type": "addition", "operandOne": 5, "operandTwo": 3 } Operation result
/api/operation/records DELETE { "ids": [1, 2, 3] } Soft delete confirmation

Operation Types and Costs

Operation Type Cost Parameters
Addition addition 1.0 operandOne, operandTwo
Subtraction subtraction 1.0 operandOne, operandTwo
Multiplication multiplication 2.0 operandOne, operandTwo
Division division 2.0 operandOne, operandTwo
Square Root square_root 3.0 operandOne
Random String random_string 5.0 -

💻 Local Development

Prerequisites

# Required tools
.NET 8 SDK          # https://dotnet.microsoft.com/download
Node.js 20+ LTS     # https://nodejs.org/
Git                 # https://git-scm.com/
AWS CLI             # https://aws.amazon.com/cli/

Database Setup

  1. Aurora Serverless v2 is deployed via CloudFormation
  2. Connection available at CloudFormation Output: AuroraClusterEndpoint
  3. Database name: calcdb
  4. Initialize with Entity Framework migrations

Running Locally

# Clone repositories
git clone https://github.com/luangrezende/arithmetic-calculator-operation-api.git
git clone https://github.com/luangrezende/arithmetic-calculator-user-api.git
git clone https://github.com/luangrezende/arithmetic-calculator-ui.git

# Terminal 1: Operation API
cd arithmetic-calculator-operation-api
dotnet restore
dotnet run --urls http://localhost:5000

# Terminal 2: User API
cd arithmetic-calculator-user-api
dotnet restore
dotnet run --urls http://localhost:5001

# Terminal 3: Frontend
cd arithmetic-calculator-ui
npm install
npm run dev
# Access at http://localhost:5173

🏗️ Technical Implementation

Architecture & Patterns

  • Clean Architecture with DI
  • Repository Pattern
  • Entity Framework Core 8
  • AWS Lambda integration
  • RESTful API design
  • Mediator pattern

Infrastructure & Scalability

  • Aurora Serverless v2 (0.5-1.0 ACUs)
  • CloudFront global CDN
  • VPC network isolation
  • Auto-scaling Lambda functions
  • S3 static hosting
  • API Gateway throttling

Security & Compliance

  • JWT Bearer tokens
  • BCrypt password hashing
  • VPC Security Groups
  • Private subnets for Lambda
  • CORS configuration
  • HTTPS only (TLS 1.2+)

🔄 CI/CD Pipeline

graph LR
    A[Code Push]:::push --> B[GitHub Actions]:::github
    B --> C[Run Tests]:::test
    C --> D[Build Application]:::build
    D --> E[Package Lambda/Frontend]:::package
    E --> F{Manual Deploy?}:::decision
    F -->|Yes| G[Deploy to AWS]:::deploy
    F -->|No| H[Finish]:::finish
    G --> I[Update Lambda/S3]:::aws
    I --> J[Invalidate CloudFront]:::cdn
    J --> K[Create GitHub Release]:::release
    K --> H
    
    classDef push fill:#2088FF,stroke:#1368CE,stroke-width:2px,color:#fff
    classDef github fill:#24292E,stroke:#000,stroke-width:2px,color:#fff
    classDef test fill:#28A745,stroke:#22863A,stroke-width:2px,color:#fff
    classDef build fill:#6F42C1,stroke:#553C9A,stroke-width:2px,color:#fff
    classDef package fill:#FD7E14,stroke:#DC6A0C,stroke-width:2px,color:#fff
    classDef decision fill:#FFC107,stroke:#D39E00,stroke-width:2px,color:#000
    classDef deploy fill:#FF9900,stroke:#CC7A00,stroke-width:2px,color:#fff
    classDef aws fill:#232F3E,stroke:#FF9900,stroke-width:2px,color:#fff
    classDef cdn fill:#0073BB,stroke:#005A9C,stroke-width:2px,color:#fff
    classDef release fill:#0366D6,stroke:#024FA1,stroke-width:2px,color:#fff
    classDef finish fill:#DC3545,stroke:#BD2130,stroke-width:2px,color:#fff
Loading

Deployment Workflow

  1. Automatic on push to master: Build and test only
  2. Manual deployment: Full deployment to AWS
  3. Semantic versioning: Auto-increment based on commit messages
  4. Release creation: Automatic GitHub releases with changelog

AWS Resources Created

Network Resources

  • VPC with 10.0.0.0/16 CIDR block
  • 2 public subnets (10.0.1.0/24, 10.0.2.0/24)
  • 2 private subnets (10.0.11.0/24, 10.0.12.0/24)
  • Internet Gateway for public access
  • Route tables for network routing
  • VPC Endpoints for Lambda and S3

Security Resources

  • Lambda Security Group
  • Database Security Group
  • VPC Endpoints Security Group
  • IAM Role for Lambda execution
  • S3 Bucket Policy for CloudFront
  • API Gateway resource policies

Application Resources

  • Aurora Serverless v2 MySQL cluster
  • API Gateway REST API with CORS
  • CloudFront Distribution with caching
  • S3 Bucket for frontend hosting
  • Lambda functions in VPC
  • CloudWatch log groups

Estimated Monthly Costs

Service Configuration Estimated Cost
Aurora Serverless v2 0.5 ACU minimum ~$43/month
Lambda 2 functions, light usage ~$5/month
API Gateway <1M requests ~$3.50/month
S3 + CloudFront Static hosting + CDN ~$5/month
VPC Endpoints Lambda endpoint ~$7/month
Total ~$65/month

🔧 Troubleshooting

Common Issues

Issue Solution
Lambda timeout Check VPC configuration and security groups
CORS errors Verify API Gateway CORS configuration and CloudFront headers
Database connection Ensure Lambda is in correct VPC and security group allows MySQL port
Random string fails Lambda needs internet access (NAT Gateway required for Random.org)
CloudFront 403 Check S3 bucket policy and CloudFront OAI configuration

Health Check Commands

# Check API Gateway health
curl https://<cloudfront-domain>/api/user/health
curl https://<cloudfront-domain>/api/operation/health

# Check Lambda logs
aws logs tail /aws/lambda/ArithmeticCalculatorUserApi --follow
aws logs tail /aws/lambda/ArithmeticCalculatorOperationApi --follow

# Check CloudFront distribution
aws cloudfront get-distribution --id <distribution-id>

🤝 Contributing

Development Workflow

  1. Fork the repository
  2. Create a feature branch (feature/your-feature)
  3. Commit changes with semantic commit messages
  4. Push to your fork
  5. Create a Pull Request to master

Commit Message Format

type: description

types: feat, fix, docs, style, refactor, test, chore

Code Quality Standards

  • Test Coverage: Minimum 80%
  • Linting: ESLint for TypeScript, Roslyn analyzers for .NET
  • Type Safety: TypeScript strict mode, nullable reference types in C#
  • Documentation: XML comments for public APIs

📖 Support & Resources

Documentation

Issue Reporting

  • Operation API: GitHub Issues
  • User API: GitHub Issues
  • Frontend: GitHub Issues

✅ Project Status

Production Ready Features:

  • ✅ Infrastructure as Code (CloudFormation)
  • ✅ Serverless Architecture (Lambda + Aurora Serverless)
  • ✅ Modern Frontend (React 18.3 + TypeScript + Vite)
  • ✅ Clean Architecture (SOLID principles)
  • ✅ Security (JWT + BCrypt + VPC)
  • ✅ CI/CD (GitHub Actions)
  • ✅ Global CDN (CloudFront)
  • ✅ Auto-scaling (Lambda + Aurora)

Known Limitations:

  • ⚠️ NAT Gateway (Not included - Random.org API requires internet access)

Note: Current infrastructure doesn't include NAT Gateway for cost optimization. Lambda functions in private subnets cannot access external APIs (Random.org). To enable random string generation, either:

  1. Add NAT Gateway (~$45/month)
  2. Move Lambda to public subnet (less secure)
  3. Use internal random generation (recommended)

MIT License

Clone this wiki locally