How aws-samples/eb-java-scorekeep works
Project Type and Purpose
• Scorekeep is a full-stack web application comprising:
– A Java/Spring Boot REST API (“backend”)
– An Angular 1.5 single-page app (“frontend”)
– AWS infrastructure (DynamoDB, SNS, Elastic Beanstalk, S3/CDN, CloudFormation)
• Purpose: allow users to create and play game sessions, persist via DynamoDB, notify via SNS.
File Structure
• Top-level build & deployment files
– build.gradle, gradlew*, Buildfile, Procfile, template.yml
– .ebextensions/ configures nginx and AWS resources at deploy time
– bin/*.sh scripts for bucket creation, deploy, run/test locally, cleanup
• Frontend
– public/ serves static HTML/CSS/JS via nginx
– public/app/ contains Angular controllers, collections, services, routes
• Backend
– src/main/java/scorekeep/
• Controller classes (GameController, SessionController, etc.)
• Model classes (GameModel, SessionModel, etc.)
• Factory classes for object creation
• Exception types for not-found or rules errors
• SimpleCORSFilter and WebConfig for HTTP/CORS setup
• Sns.java wrapper for SNS notifications
– src/main/resources/application.properties for AWS region, table names
• Tests
– Unit test under src/test/java/scorekeep/TicTacToeTest.java
Extract Architecture Insights from README
• Two independent components: static Angular app + Spring Boot API
• nginx (via .ebextensions/nginx.conf) serves / → static files, proxies /api → port 5000
• API endpoints under /api/{user,session,game,state,move} interact with DynamoDB tables
• SNS topic publishes “game over” notifications
• CloudFormation (template.yml) creates DynamoDB tables, SNS topic, IAM roles
• Elastic Beanstalk runs everything in a single environment by default (other branches show Docker/ECS, Fargate, Lambda, SQL, X-Ray integrations)
Components & Interactions—How to Represent Them
a. Main Components
• Client Browser / User Interface (Angular 1.5 SPA)
• nginx (static file server & reverse proxy)
• Spring Boot REST API (Java application)
• Amazon DynamoDB tables (Users, Sessions, Games, States, Moves)
• Amazon SNS topic (notification publisher)
• AWS Elastic Beanstalk environment (EC2 instance, IAM role)
• (Optional) S3/CloudFront CDN for static assets
• CloudFormation orchestration
b. Relationships and Data Flows
1. User → HTTP GET / → nginx → serves HTML/JS/CSS
2. Angular app → HTTP calls ($resource) → /api/... paths
3. nginx (port 80) proxies /api → Spring Boot (port 5000)
4. Spring Boot controllers → DynamoDB SDK calls → Read/Write tables
5. On game completion → Spring Boot → SNS SDK → Publish to SNS topic → Email/SMS
6. CloudFormation (deploy time) → Creates DynamoDB tables, SNS topic, IAM roles
7. Elastic Beanstalk environment → Deploys JAR (via Buildfile/Procfile) → Runs API
8. (Local dev) Scripts set environment variables for AWS_REGION, table names, topic ARN
c. Architectural Patterns & Principles
• RESTful resource-oriented API (controllers, models, exceptions)
• MVC-style separation in Angular (controllers, services, routes)
• Infrastructure as Code (CloudFormation, .ebextensions)
• Reverse proxy pattern (nginx → API)
• Factory pattern (RuleFactory, GameFactory) and simple dependency injection via Spring
• CORS filter to allow cross-origin local dev
d. Key Technologies & Frameworks
• Angular 1.5 $resource
• Spring Boot (embedded Tomcat, bootRun)
• AWS SDK for Java (DynamoDB, SNS)
• Amazon DynamoDB (NoSQL storage)
• Amazon SNS (notification service)
• AWS Elastic Beanstalk (app hosting)
• nginx (static + proxy)
• Gradle (build)