How hypest/simple-webapp-localstack works
Project type and purpose
• This is a full-stack web application built on Ruby on Rails (MVC) that implements a simple counter feature.
• It uses AWS SQS (via LocalStack) for inter-instance messaging, Sidekiq + Redis for background jobs, Terraform for infrastructure as code, and Docker/devcontainers for reproducible development.
File structure
Top-level directories:
• .devcontainer – VS Code devcontainer setup (Dockerfile, scripts).
• app – the Rails application (standard MVC folders: controllers, models, views, assets, config, jobs, mailers).
• app-docker-images – separate Dockerfiles for development and production images.
• infrastructure – Terraform code defining LocalStack provider, SQS queues, VPC, ECR, EC2, etc.
• scripts – shell scripts for setup, deploying, registry bridging, starting/stopping LocalStack & Redis.
Patterns & artifacts:
• MVC structure in app/
• Sidekiq + Redis (config/queue.yml, config/redis URL)
• SQS queues and DLQ managed by Terraform (infrastructure/sqs.tf)
• Devcontainer config orchestrates Rails, AWS CLI, Terraform in a single container
• CI workflow (.github/workflows/ci.yml), Kamal hooks for deploy, GitHub Actions, Git attributes
README for additional insights
• Services in development: Rails server (port 3000), LocalStack (4566), Redis (6379)
• AWS resources emulated: counter-queue & counter-queue-dlq
• Environment variables for AWS credentials, LocalStack endpoint, Redis URL, queue URL
• Instructions to run Terraform, Rails, AWS CLI commands targeting LocalStack
a. Main components
• Clients (Web browsers/mobile)
• Rails web application (Puma server)
• Background job processor (Sidekiq)
• Redis (session store & Sidekiq backend)
• AWS SDK → LocalStack (SQS queue + DLQ)
• Development database (SQLite in dev, could be Postgres in prod)
• Infrastructure-as-Code (Terraform)
• Container runtime (Docker, Devcontainer)
b. Relationships & interactions
1. Client sends HTTP requests to Rails (Puma).
2. Rails controller updates counter in DB and pushes a message to SQS via AWS SDK (endpoint=LocalStack).
3. Sidekiq worker polls Redis for new jobs; jobs process incoming SQS messages (or enqueue SQS read tasks).
4. Processed events may update the DB or notify live clients (ActionCable or polling).
5. Terraform provisions SQS queues & DLQ in LocalStack before the app bootstraps.
6. Docker/devcontainer orchestrates all services (Rails, Redis, LocalStack) in isolated containers.
c. Architectural patterns & design principles
• MVC for web tier
• Publish-subscribe (via SQS) for inter-instance communication
• Asynchronous processing (Sidekiq + Redis)
• Infrastructure as code (Terraform)
• Containerization & reproducible dev environments (Docker, Devcontainers)
d. Key technologies/frameworks
• Ruby on Rails 7, Puma
• Redis, Sidekiq
• AWS SDK → LocalStack (SQS)
• Docker & Docker Compose, VS Code Devcontainers
• Terraform (infrastructure/)
• GitHub Actions (CI) & Kamal (deployment hooks)