{"id":49243059,"url":"https://github.com/anyulled/superhero-battle-arena","last_synced_at":"2026-04-24T20:12:35.695Z","repository":{"id":334783756,"uuid":"1142764058","full_name":"anyulled/superhero-battle-arena","owner":"anyulled","description":"Super Hero Battle Arena - Java Application made for the Talent Arena workshop","archived":false,"fork":false,"pushed_at":"2026-04-20T07:47:38.000Z","size":7372,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T09:36:42.425Z","etag":null,"topics":["antigravity","clean-architecture","java","spring-boot","testcontainers"],"latest_commit_sha":null,"homepage":"https://superhero-battle-arena.barcelonajug.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anyulled.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-26T20:35:20.000Z","updated_at":"2026-04-14T13:30:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anyulled/superhero-battle-arena","commit_stats":null,"previous_names":["anyulled/superhero-battle-arena"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/anyulled/superhero-battle-arena","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anyulled%2Fsuperhero-battle-arena","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anyulled%2Fsuperhero-battle-arena/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anyulled%2Fsuperhero-battle-arena/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anyulled%2Fsuperhero-battle-arena/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anyulled","download_url":"https://codeload.github.com/anyulled/superhero-battle-arena/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anyulled%2Fsuperhero-battle-arena/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32238913,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["antigravity","clean-architecture","java","spring-boot","testcontainers"],"created_at":"2026-04-24T20:12:34.800Z","updated_at":"2026-04-24T20:12:35.686Z","avatar_url":"https://github.com/anyulled.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Superhero Battle Arena\n\n![Superhero Battle Arena Hero Image](src/main/resources/static/images/hero-image.png)\n\n[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/anyulled/superhero-battle-arena)\n[![AI Harness Scorecard](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fanyulled%2Fsuperhero-battle-arena%2Fscorecard%2Fscorecard-badge.json)](https://github.com/anyulled/superhero-battle-arena/blob/scorecard/scorecard-report.md)\n[![CI](https://github.com/anyulled/superhero-battle-arena/actions/workflows/ci.yml/badge.svg)](https://github.com/anyulled/superhero-battle-arena/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/anyulled/superhero-battle-arena/graph/badge.svg?token=CODECOV_TOKEN)](https://codecov.io/gh/anyulled/superhero-battle-arena)\n[![Known Vulnerabilities](https://snyk.io/test/github/anyulled/superhero-battle-arena/badge.svg)](https://snyk.io/test/github/anyulled/superhero-battle-arena)\n[![Java](https://img.shields.io/badge/Java-25-orange?logo=openjdk)](https://openjdk.org/projects/jdk/25/)\n[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.x-brightgreen?logo=spring)](https://spring.io/projects/spring-boot)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=anyulled_superhero-battle-arena\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=anyulled_superhero-battle-arena)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n| | |\n| :---: | :---: |\n| [![Barcelona JUG](src/main/resources/static/images/barcelonajug.png)](https://barcelonajug.org) | [![Talent Arena](src/main/resources/static/images/talentArena.png)](https://talentarena.tech) |\n\nA Spring Boot application built with Hexagonal Architecture that simulates battles between teams of superheroes.\n\n## Features\n\n- **Team Management**: Register your team of superheroes.\n- **Squad Formation**: Submit specific hero lineups and strategies for each round.\n- **Matchmaking**: Create matches between two registered teams within a session.\n- **Battle Simulation**: Deterministic battle engine with turn-based combat mechanics and fatigue system.\n- **Live Replay**: Watch battles unfold in real-time via Server-Sent Events (SSE) with visual animations.\n- **Hexagonal Architecture**: Clean separation of concerns with Domain, Application (Use Cases), and Adapter layers.\n\n## Technology Stack\n\n- **Backend**: Java 25 (Preview Features), Spring Boot 4.x\n- **Frontend**: HTML5, Tailwind CSS, jQuery, Lucide Icons\n- **Architecture**: Hexagonal (Ports \u0026 Adapters) with Use Case pattern\n- **Build Tool**: Maven\n\n## How to Run\n\n1. **Prerequisites**: Ensure you have Java 21+ installed (Java 25 recommended for full compatibility).\n2. **Build and Run**:\n\n   ```bash\n   ./mvnw spring-boot:run\n   ```\n\n### Spring Profiles\n\nThe application supports different environments through Spring profiles:\n\n- **`h2` (Default)**: Uses an in-memory H2 database. Perfect for local development.\n\n  ```bash\n  ./mvnw spring-boot:run -Dspring-boot.run.profiles=h2\n  ```\n\n- **`postgres`**: Uses an external PostgreSQL database managed by **Docker Compose**. Spring Boot will automatically start a PostgreSQL container using `docker-compose.yml`.\n\n  ```bash\n  ./mvnw spring-boot:run -Dspring-boot.run.profiles=postgres\n  ```\n\n#### Troubleshooting Podman\n\nIf you are using **Podman** instead of Docker, the `spring-boot-docker-compose` module may fail to find the `docker` command. You can resolve this by:\n\n1. **Creating a symlink** (recommended):\n\n   ```bash\n   sudo ln -s $(which podman) /usr/local/bin/docker\n   ```\n\n2. **Ensuring the Podman machine is running**:\n\n   ```bash\n   podman machine start\n   ```\n\n3. **Setting the `DOCKER_HOST`** if necessary:\n\n   ```bash\n   export DOCKER_HOST=\"unix://$(podman machine inspect --format '{{.RuntimeDirectories.Internal}}' | jq -r '.[0]')/podman.sock\"\n   ```\n\n4. **Fixing Credential Helper Errors**:\n\n   If you see an error like `exec: \"docker-credential-desktop\": executable file not found`, it's because your `~/.docker/config.json` is configured to use Docker Desktop's credential store. Fix it by removing the `credsStore` line:\n\n   ```bash\n   sed -i '' '/\"credsStore\": \"desktop\"/d' ~/.docker/config.json\n   ```\n\n5. **Access the Application**:\n\n   Open your browser to [http://localhost:8080/](http://localhost:8080/) (the main entry point).\n\n6. **API Documentation**:\n   - Swagger UI: [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)\n   - OpenAPI JSON: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs)\n\n## Architecture\n\n### System Overview\n\n```mermaid\ngraph TD\n    User[User Browser]\n    \n    subgraph \"Superhero Battle Arena\"\n        Web[\"Web Adapter (Controllers)\"]\n        App[\"Application Layer (Use Cases)\"]\n        Domain[\"Domain Layer (Entities/Logic)\"]\n        Persist[Persistence Adapter]\n    end\n    \n    User \u003c--\u003e|HTTP/REST/SSE| Web\n    Web --\u003e App\n    App --\u003e Domain\n    App --\u003e|Ports| Persist\n```\n\n## Battle Flow\n\nThe system flow is divided into four main phases: Registration, Squad Submission, Matchmaking, and Battle.\n\n### Phase 1: Registration (Session \u0026 Teams)\n\n```mermaid\nsequenceDiagram\n    participant U as User/Admin\n    participant C as SessionController\n    participant T as TeamController\n    participant R as Repository\n\n    U-\u003e\u003eC: POST /api/sessions\n    C-\u003e\u003eR: Save New Session\n    C--\u003e\u003eU: Session ID\n    \n    U-\u003e\u003eT: POST /api/teams/register (with Session ID)\n    T-\u003e\u003eR: Save Team\n    T--\u003e\u003eU: Team ID\n```\n\n### Phase 2: Squad Submission\n\nBefore a match can be run for a specific round, teams must submit their squad (list of heroes) and strategy.\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant SC as SubmissionController\n    participant R as Repository\n\n    U-\u003e\u003eSC: POST /api/submissions (Team ID, Round No, Hero IDs, Strategy)\n    SC-\u003e\u003eR: Save Submission\n    SC--\u003e\u003eU: Confirmed\n```\n\n### Phase 3: Matchmaking \u0026 Round Setup\n\n```mermaid\nsequenceDiagram\n    participant U as Admin\n    participant RC as RoundController\n    participant MC as MatchController\n    participant R as Repository\n\n    U-\u003e\u003eRC: POST /api/rounds (Session ID, Round No)\n    RC-\u003e\u003eR: Save Round Config\n    \n    U-\u003e\u003eMC: POST /api/matches/auto (Session ID, Round No)\n    MC-\u003e\u003eR: Create Pending Matches for all submissions\n    MC--\u003e\u003eU: Match IDs\n```\n\n### Phase 4: Battle Simulation \u0026 Visualization\n\n```mermaid\nsequenceDiagram\n    participant U as User\n    participant F as Frontend\n    participant MC as MatchController\n    participant E as BattleEngineUseCase\n\n    U-\u003e\u003eF: Watch Match\n    F-\u003e\u003eMC: POST /api/matches/{id}/run\n    MC-\u003e\u003eE: simulate(match)\n    E--\u003e\u003eMC: Full Battle Result (Winner, Events)\n    MC--\u003e\u003eF: Match Completed\n    \n    F-\u003e\u003eMC: GET /api/matches/{id}/events/stream\n    loop Replay\n        MC--\u003e\u003eF: SSE Event (ATTACK, HEALTH_CHANGED, etc.)\n        F-\u003e\u003eF: Animate Health Bars and Effects\n    end\n```\n\n## Domain Model\n\nKey domain entities use the **Builder Pattern** and are implemented as Java **Records** where immutable data transfer is required.\n\n```mermaid\nclassDiagram\n    class Match {\n        UUID matchId\n        UUID sessionId\n        UUID teamA\n        UUID teamB\n        Integer roundNo\n        MatchStatus status\n        MatchResult result\n    }\n    \n    class Team {\n        UUID teamId\n        String name\n        List~String~ members\n    }\n    \n    class Hero {\n        int id\n        String name\n        String slug\n        PowerStats powerstats\n        String role\n        Integer cost\n        List~String~ tags\n    }\n    \n    class MatchEvent {\n        String type\n        int actorId\n        int targetId\n        int value\n    }\n    \n    Match --\u003e MatchStatus\n    Match --\u003e MatchResult\n    Hero \"1\" *-- \"1\" PowerStats\n```\n\n### Match Events\n\nThe simulation generates various event types delivered via SSE:\n\n- `START_BATTLE`: Initialization of the combat scene.\n- `ATTACK`: When a hero performs an action.\n- `HEALTH_CHANGED`: Updates hero health bars in the UI.\n- `BATTLE_OVER`: Final result including the winner.\n\n## Usage Guide\n\n1. **Home**: Start at `index.html`.\n2. **Lobby**: Manage teams and see active sessions. Registration is done via API (see samples in `/lobby.html`).\n3. **Admin**: Configure rounds and trigger auto-matchmaking.\n4. **Current Bracket**: View the tournament progress on `bracket.html`.\n5. **Watch Battle**: Experience the real-time simulation on `battle.html`.\n\n## Command-Line Tools\n\nThe repository includes several utility scripts for data initialization and SQL generation.\n\nSee the [Scripts Documentation](scripts/README.md) for detailed instructions on using JBang to:\n\n- Initialize test fixtures (`InitFixture.java`)\n- Generate seed SQL from JSON (`GenerateSuperheroSql.java`)\n- Extract hero data (`ExtractHeroes.java`)\n\n## Development\n\nThe project structure follows Hexagonal Architecture principles:\n\n- `domain`: Pure business logic and entities. No framework dependencies.\n- `application`: Use cases (service layer) and input/output ports.\n- `adapter`: Implementation of ports (Web/Rest, Persistence/JPA).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanyulled%2Fsuperhero-battle-arena","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanyulled%2Fsuperhero-battle-arena","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanyulled%2Fsuperhero-battle-arena/lists"}