# aws-samples/eb-java-scorekeep architecture

> Architecture diagram of the GitHub repository aws-samples/eb-java-scorekeep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/eb-java-scorekeep
- Repository: https://github.com/aws-samples/eb-java-scorekeep

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    Browser["User Browser\n(Angular 1.5 SPA)"]:::frontend
    Browser -->|"HTTP GET /"| CDN["S3/CloudFront\nStatic Assets"]:::aws

    %% AWS CDN serves static Angular app
    CDN -->|"serves index.html, JS, CSS"| nginx_ng["nginx\n(static + proxy)"]:::compute

    subgraph "Elastic Beanstalk Environment"
        direction TB
        nginx_ng
        API["Spring Boot\nREST API\n(Port 5000)"]:::compute
    end

    %% API interactions with AWS services
    API -->|"AWS SDK Read/Write"| DynamoDB["DynamoDB Tables\n(Users, Sessions,\nGames, States, Moves)"]:::aws
    API -->|"AWS SDK Publish"| SNS["SNS Topic\n(game over notifications)"]:::aws

    %% Provisioning Infrastructure
    CloudFormation["CloudFormation\n(template.yml)"]:::infra
    CloudFormation -->|"provisions"| DynamoDB
    CloudFormation -->|"provisions"| SNS
    CloudFormation -->|"provisions"| ElasticBeanstalk["Elastic Beanstalk\nEnvironment"]:::aws

    %% Local Dev & Deployment Scripts
    InfraScripts["Deployment Scripts\n(./bin/*.sh)"]:::infra
    InfraScripts -->|"runs"| CloudFormation

    %% Click Events
    click CDN "https://github.com/aws-samples/eb-java-scorekeep/tree/master/public/app"
    click nginx_ng "https://github.com/aws-samples/eb-java-scorekeep/blob/master/.ebextensions/nginx.conf"
    click nginx_ng "https://github.com/aws-samples/eb-java-scorekeep/tree/master/Procfile"
    click API "https://github.com/aws-samples/eb-java-scorekeep/blob/master/src/main/java/scorekeep/Application.java"
    click CloudFormation "https://github.com/aws-samples/eb-java-scorekeep/blob/master/template.yml"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef compute fill:#FFDDA0,stroke:#333,stroke-width:1px
    classDef aws fill:#C2F0C2,stroke:#333,stroke-width:1px
    classDef infra fill:#F0F0F0,stroke:#333,stroke-width:1px
```
