# hypest/simple-webapp-localstack architecture

> Architecture diagram of the GitHub repository hypest/simple-webapp-localstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hypest/simple-webapp-localstack
- Repository: https://github.com/hypest/simple-webapp-localstack

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Client["Client (Browser/Mobile)"]:::client

    %% Web Tier
    subgraph "Web Tier" 
        direction TB
        RailsApp["Rails Application (Puma)"]:::web
        subgraph "Rails Components"
            direction TB
            Controllers["Controllers"]:::webComp
            Models["Models"]:::webComp
            Views["Views"]:::webComp
            Jobs["Sidekiq Jobs (app/jobs)"]:::webComp
            QueueCfg["config/queue.yml"]:::webComp
        end
        Sidekiq["Sidekiq Workers"]:::worker
    end

    %% Data Tier
    subgraph "Data Tier"
        direction TB
        DB["Database\n(SQLite/Postgres)"]:::database
        Redis["Redis\n(Sessions & Sidekiq)"]:::cache
    end

    %% Messaging Tier
    subgraph "Messaging Tier"
        direction TB
        SQS["SQS Queue & DLQ\n(LocalStack)"]:::message
    end

    %% Infrastructure
    subgraph "Infrastructure & Dev Environments"
        direction TB
        Terraform["Terraform IaC"]:::infra
        Devcontainer["Docker / Devcontainer"]:::infra
        AppImages["App Docker Images\n(Dockerfile.dev & prod)"]:::infra
        CI["GitHub Actions CI/CD"]:::infra
        Kamal["Kamal Deployment Hooks"]:::infra
        Scripts["Startup Scripts"]:::infra
    end

    %% Connections
    Client -->|"HTTP/S Request"| RailsApp
    RailsApp -->|"Update Counter"| DB
    RailsApp -->|"Enqueue SQS Message"| SQS
    RailsApp -->|"Session Store"| Redis
    Sidekiq -->|"Poll Queue"| Redis
    Sidekiq -->|"Consume SQS"| SQS
    Sidekiq -->|"Process & Update"| DB
    Sidekiq -->|"Notify Clients"| Client
    Terraform -->|"Provision SQS & DLQ"| SQS
    Devcontainer --> RailsApp
    Devcontainer --> Redis
    Devcontainer --> SQS
    Devcontainer --> Terraform

    %% Click Events
    click RailsApp "https://github.com/hypest/simple-webapp-localstack/tree/main/app/"
    click Controllers "https://github.com/hypest/simple-webapp-localstack/tree/main/app/app/controllers"
    click Models "https://github.com/hypest/simple-webapp-localstack/tree/main/app/app/models"
    click Views "https://github.com/hypest/simple-webapp-localstack/tree/main/app/app/views"
    click Jobs "https://github.com/hypest/simple-webapp-localstack/tree/main/app/app/jobs"
    click QueueCfg "https://github.com/hypest/simple-webapp-localstack/blob/main/app/config/queue.yml"
    click SQS "https://github.com/hypest/simple-webapp-localstack/blob/main/infrastructure/sqs.tf"
    click Terraform "https://github.com/hypest/simple-webapp-localstack/tree/main/infrastructure/"
    click Devcontainer "https://github.com/hypest/simple-webapp-localstack/tree/main/.devcontainer/"
    click AppImages "https://github.com/hypest/simple-webapp-localstack/blob/main/app-docker-images/Dockerfile.dev"
    click CI "https://github.com/hypest/simple-webapp-localstack/blob/main/app/.github/workflows/ci.yml"
    click Kamal "https://github.com/hypest/simple-webapp-localstack/tree/main/app/.kamal/hooks/"
    click Scripts "https://github.com/hypest/simple-webapp-localstack/blob/main/scripts/start-supporting-services.sh"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#90CAF9,color:#0D47A1;
    classDef web fill:#BBDEFB,stroke:#42A5F5,color:#1565C0;
    classDef webComp fill:#E3F2FD,stroke:#64B5F6,color:#0D47A1;
    classDef worker fill:#C8E6C9,stroke:#66BB6A,color:#1B5E20;
    classDef database fill:#FFF9C4,stroke:#FFEE58,color:#F57F17;
    classDef cache fill:#FFE0B2,stroke:#FFB74D,color:#E65100;
    classDef message fill:#F3E5F5,stroke:#BA68C8,color:#4A148C;
    classDef infra fill:#ECEFF1,stroke:#B0BEC5,color:#263238;
```
