How amazon-archives/microservices-webapp works
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.