# amazon-archives/microservices-webapp architecture

> Architecture diagram of the GitHub repository amazon-archives/microservices-webapp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amazon-archives/microservices-webapp
- Repository: https://github.com/amazon-archives/microservices-webapp

## Overview

##### Project type and purpose (what you’re diagramming)

- **Containerized webapp** (e.g., behind an ALB) — indicated by `Dockerfile`.
- **AWS Lambda deployment** — indicated by `webapp-sam.yaml` and `src/assembly/lambda.xml` (custom assembly for a Lambda-friendly artifact).

##### What the file tree reveals (how to map code to architecture)
Key artifacts and what they imply:

##### Build + packaging
- `pom.xml` → Maven build, dependencies, packaging type (likely `jar`/`war`) and plugins.
- `Dockerfile` → container image build; implies a container runtime target (ECS/EKS/EC2).
- `src/assembly/lambda.xml` → Maven Assembly (or similar) to create a zip layout for Lambda.
- `webapp-sam.yaml` → AWS SAM template describing Lambda, event source (often API Gateway), IAM, etc.

##### Application runtime (Java webapp)
- `src/main/webapp/WEB-INF/web.xml` → classic Java webapp descriptor (Servlet container model).
- `src/main/java/.../MyApplication.java` → often a JAX-RS `Application` / bootstrapping class (or framework bootstrap).
- `WebappController.java` → request/route handling layer (HTTP endpoints).
- `WebappHandler.java` → likely the Lambda entrypoint or adapter for Lambda proxy events.
- `StartupBean.java` → initialization lifecycle hook (DI container / servlet context listener / framework bean).

**Implication for diagramming:** there’s a clean separation between:
- **Edge / HTTP entry** (ALB or API Gateway)
- **Compute runtime** (Container servlet runtime vs Lambda runtime)
- **App layers** (controller/handler + startup/bootstrap)
- **Static web resources** (anything under `src/main/webapp`)

What exists in this repo:

- **HTTP Interface Layer**
- `WebappController` (HTTP endpoints)
- `web.xml` (routing/servlet config)
- `MyApplication` (application bootstrap/routing config if JAX-RS)
- **Lambda Adapter Layer (if used)**
- `WebappHandler` (translates API Gateway/Lambda event → internal controller or service calls)
- **Initialization**
- `StartupBean` (startup initialization, config wiring)
- **Web UI/Static Assets**
- `src/main/webapp/**` (pages/assets served by the web layer)

- Requests entering via HTTP → controller (or handler) → response.
- StartupBean initializing configuration used by controllers/handlers.

Because the repo explicitly supports multiple deployment forms, show **two deployment options**:

##### Option 1: Container-based deployment
Typical flow (label generically if the parent repo chooses ECS/EKS):
##### Client (Browser/User)
→ 2. **Load Balancer (ALB)**
→ 3. **Container Runtime (ECS task / EKS pod / EC2 + Docker)** running **Webapp Microservice container**
→ returns response to Client

Artifacts to label:
- `Dockerfile` → “Container Image Build”
- `pom.xml` → “Build artifact packaged into image”

##### Option 2: Serverless deployment (SAM/Lambda)
Typical flow:
##### Client (Browser/User)
→ 2. **API Gateway (HTTP API / REST API)**
→ 3. **AWS Lambda: Webapp Microservice function**
→ returns response to Client

Artifacts to label:
- `webapp-sam.yaml` → “SAM template defines API + Lambda”
- `src/assembly/lambda.xml` → “Lambda zip assembly”

##### External actors
- **End user / Browser / HTTP client**

##### Edge / ingress
- **ALB** (container option)
- **API Gateway** (Lambda option)

##### Compute
- **Containerized Webapp Service**
- **Lambda Function Webapp Service**

- **Routing/Bootstrap** (`MyApplication`, `web.xml`)
- **Request handling** (`WebappController`)
- **Lambda handler adapter** (`WebappHandler`) — only in Lambda path
- **Startup/initialization** (`StartupBean`)
- **Static content** (`src/main/webapp`)

##### Build/deploy pipeline (optional but recommended for “accurate system design”)
- **Maven build** (`pom.xml`)
- **Container build** (`Dockerfile`)
- **SAM packaging/deploy** (`webapp-sam.yaml`, `lambda.xml`)

- Build pipeline: Source → Maven → (Docker build → registry → runtime) and/or (SAM package → Lambda).
- Runtime request flow: Client → Edge → Compute → App components → Response.

##### Add two deployment lanes inside or beside it
- Lane A: “Container Deployment (Dockerfile)”
- Lane B: “Serverless Deployment (SAM/Lambda)”
- Bootstrap/config: `MyApplication`, `web.xml`, `StartupBean`
- Request handling: `WebappController`
- Lambda entrypoint: `WebappHandler` (Lambda lane only)
- Static assets: `src/main/webapp`
##### Add build artifacts feeding each lane
- `pom.xml` to both lanes
- `Dockerfile` to container lane
- `lambda.xml` + `webapp-sam.yaml` to Lambda lane
##### Annotate “unknowns” rather than guessing
- If no database clients/config are present, omit DB.
- If no outbound integrations are visible, omit them.
- A small “Verify in parent repo” note for networking/VPC, observability, auth, etc.

- **Clear labels**: use file/class names to prove traceability (e.g., “WebappHandler (src/main/java/.../WebappHandler.java)”).
- Compute workloads (Container, Lambda runtime) in another.
- Internal code components (controller/handler/bootstrap) in a third.
- Build artifacts/pipeline nodes (Maven, Docker build, SAM deploy) in gray.

##### What “detailed” means here (without overthinking)
Decompose aggressively, but only into components that are evidenced by the repo:
- Treat **each deploy target** (container vs lambda) as a first-class component.
- Treat **build/deploy descriptors** (`pom.xml`, `Dockerfile`, `webapp-sam.yaml`, `lambda.xml`) as explicit nodes feeding the runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD

%% External Actor
Client["EndUser/Browser<br/>(HTTP Client)"]:::external

%% Microservice boundary
subgraph "Webapp Microservice (this repo)"
direction TB

    %% Build / Packaging (shared)
    subgraph "Build & Packaging"
    direction TB
        Source["SourceCode<br/>(Java + Webapp resources)"]:::artifact
        Maven["MavenBuild<br/>(pom.xml)"]:::build

        Source -.->|"builds"| Maven
    end

    %% Deployment Option A
    subgraph "Deployment Option A: Containerized Webapp"
    direction TB
        ALB["LoadBalancer<br/>(ALB)"]:::aws

        subgraph "Container Runtime"
        direction TB
            ContainerSvc["WebappServiceContainer<br/>(Servlet Runtime)"]:::compute

            subgraph "Internal App Components (container)"
            direction TB
                WebXml["web.xml<br/>(Servlet config/routing)"]:::code
                MyApp["MyApplication<br/>(bootstrap/routing)"]:::code
                Startup["StartupBean<br/>(initialization)"]:::code
                Controller["WebappController<br/>(HTTP endpoints)"]:::code
                Static["StaticWebResources<br/>(src/main/webapp/**)"]:::static

                Startup -->|"initializes"| MyApp
                Startup -->|"initializes"| Controller
                WebXml -->|"routes_to"| Controller
                MyApp -->|"registers_routes"| Controller
                Controller -->|"serves"| Static
            end

            ContainerSvc -->|"hosts"| WebXml
            ContainerSvc -->|"hosts"| MyApp
            ContainerSvc -->|"hosts"| Startup
            ContainerSvc -->|"hosts"| Controller
            ContainerSvc -->|"serves"| Static
        end

        Docker["ContainerImageBuild<br/>(Dockerfile)"]:::build

        Maven -.->|"artifact_for_image"| Docker
        Docker -.->|"deploys_to"| ContainerSvc

        ALB -->|"http_request"| ContainerSvc
        ContainerSvc -->|"http_response"| ALB
    end

    %% Deployment Option B
    subgraph "Deployment Option B: Serverless (SAM/Lambda)"
    direction TB
        HttpEvent["SAM-definedHTTPEventSource<br/>(commonly API Gateway)"]:::aws

        subgraph "AWS Lambda Runtime"
        direction TB
            LambdaFn["WebappServiceFunction<br/>(AWS Lambda)"]:::compute

            subgraph "Internal App Components (lambda)"
            direction TB
                LambdaHandler["WebappHandler<br/>(Lambda adapter/entrypoint)"]:::code
                MyAppL["MyApplication<br/>(bootstrap/routing)"]:::code
                StartupL["StartupBean<br/>(initialization)"]:::code
                ControllerL["WebappController<br/>(HTTP endpoints)"]:::code
                StaticL["StaticWebResources<br/>(src/main/webapp/**)"]:::static

                StartupL -->|"initializes"| MyAppL
                StartupL -->|"initializes"| ControllerL
                LambdaHandler -->|"adapts_event_to_http_request"| ControllerL
                MyAppL -->|"registers_routes"| ControllerL
                ControllerL -->|"serves"| StaticL
            end

            LambdaFn -->|"invokes"| LambdaHandler
            LambdaFn -->|"uses"| MyAppL
            LambdaFn -->|"uses"| StartupL
            LambdaFn -->|"uses"| ControllerL
            LambdaFn -->|"serves"| StaticL
        end

        SAM["SAMTemplate<br/>(webapp-sam.yaml)"]:::build
        LambdaAssembly["LambdaZipAssembly<br/>(src/assembly/lambda.xml)"]:::build

        Maven -.->|"build_artifact"| LambdaAssembly
        LambdaAssembly -.->|"package_zip"| SAM
        SAM -.->|"deploys_lambda+event_source"| LambdaFn
        SAM -.->|"defines_http_event"| HttpEvent

        HttpEvent -->|"invoke"| LambdaFn
        LambdaFn -->|"response"| HttpEvent
    end

    %% Note (keep minimal; do not invent infra)
    Verify["Note:Network/VPC/Auth/Observability defined in parent repo<br/>(verify as needed)"]:::note
end

%% External request paths (vertical)
Client -->|"container_option"| ALB
ALB -->|"http_response"| Client

Client -->|"serverless_option"| HttpEvent
HttpEvent -->|"http_response"| Client

%% Click events (mapped components)
click Maven "https://github.com/amazon-archives/microservices-webapp/blob/master/pom.xml"
click Docker "https://github.com/amazon-archives/microservices-webapp/tree/master/Dockerfile"
click SAM "https://github.com/amazon-archives/microservices-webapp/blob/master/webapp-sam.yaml"
click LambdaAssembly "https://github.com/amazon-archives/microservices-webapp/blob/master/src/assembly/lambda.xml"
click WebXml "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/webapp/WEB-INF/web.xml"
click MyApp "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/MyApplication.java"
click MyAppL "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/MyApplication.java"
click Controller "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/WebappController.java"
click ControllerL "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/WebappController.java"
click LambdaHandler "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/WebappHandler.java"
click Startup "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/StartupBean.java"
click StartupL "https://github.com/amazon-archives/microservices-webapp/blob/master/src/main/java/org/aws/samples/compute/webapp/StartupBean.java"
click Static "https://github.com/amazon-archives/microservices-webapp/tree/master/src/main/webapp/"
click StaticL "https://github.com/amazon-archives/microservices-webapp/tree/master/src/main/webapp/"

%% Styles
classDef external fill:#0b1f33,stroke:#7aa2ff,color:#eaf2ff,stroke-width:1.5px;
classDef aws fill:#2b1d0e,stroke:#ffb74d,color:#fff3e0,stroke-width:1.5px;
classDef compute fill:#1b3a2b,stroke:#66bb6a,color:#e8f5e9,stroke-width:1.5px;
classDef code fill:#1f2a44,stroke:#90caf9,color:#e3f2fd,stroke-width:1.5px;
classDef static fill:#3a1b3a,stroke:#ce93d8,color:#f3e5f5,stroke-width:1.5px;
classDef build fill:#2f2f2f,stroke:#bdbdbd,color:#f5f5f5,stroke-width:1.5px;
classDef artifact fill:#3b3b3b,stroke:#9e9e9e,color:#ffffff,stroke-width:1.5px;
classDef note fill:#3a2f12,stroke:#ffd54f,color:#fff8e1,stroke-width:1.5px;
```
