# capstone-projects-2025-spring/project-acc-hungry-hippos architecture

> Architecture diagram of the GitHub repository capstone-projects-2025-spring/project-acc-hungry-hippos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/capstone-projects-2025-spring/project-acc-hungry-hippos
- Repository: https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos

## Overview

##### Project Type & Purpose
This is a full-stack, web-based, real-time multiplayer game (“Hungry Hippos”) built with:
- Frontend: React + TypeScript + Phaser 3 for UI, game logic, physics
- Backend: a lightweight Node/TypeScript WebSocket server (in server-backend/main.tsx + sessionAPI.js)
- Static assets: served directly (images, audio under public/assets & public/audio)
- Accessibility Layer: AAC interface mapped to game controls
The result is a cross-platform browser game emphasizing inclusivity and AAC support.

##### File Structure Analysis
- Top-level “Hungry-Hippo-Game” folder contains:
– public/…: static assets (images, audio) and style.css
– server-backend/: WebSocket API server entrypoint
– src/: React + Phaser code
– src/game/: Phaser engine setup, scenes, event bus, hippo & strategy classes
– src/components, src/pages: reusable UI + page routes (Landing, RoleSelect, AAC, Phaser, Presenter, Leaderboard, etc.)
– src/contexts/WebSocketContext.tsx: encapsulates socket logic
– src/data: JSON fixtures (food lists, sessionIDs)
– router.tsx: SPA routing
– build configs: tsconfig, vite.config.*.mjs, vercel.json, vitest.config.ts

- Dev & CI: .devcontainer/, .github/workflows/, Dockerfile? (none), of which workflows handle spelling, build, deploy.

##### Key Architectural Patterns
- Component-based UI (React)
- Game engine layer (Phaser) isolated from React via PhaserGame.tsx wrapper
- Context API for global WebSocket and AAC event distribution
- Strategy pattern for Hippo movement (Jump, Walk, EdgeSlide)
- SPA routing + code-splitting per page
- Server-client real-time messaging (WebSocket) for session management & multiplayer sync

##### Main Components & Data Flows
[Frontend – Client Browser]
- React UI Layer: pages + components (buttons, leaderboards, AAC panel)
- Game Engine Layer: PhaserScene rendering physics, sprites, collisions
- AAC Input Layer: translates alternative communication inputs into game events
- WebSocket Client: sends events (join session, move requests, score updates) & listens for server broadcasts
- Static Asset Loader: fetches images/audio from public/assets & public/audio

[Backend – WebSocket Server]
- Session Manager (sessionAPI.js): maintains sessionID, broadcasting, round orchestration
- WebSocket Endpoints: handle client connect/disconnect, route messages between conductor & hippo players

[Optional External Services]
- Hosting & CI/CD: Vercel (frontend), GitHub Pages (docs), GitHub Actions for build & deploy
- Docs Site (Docusaurus under documentation/)

##### Essential Details to Capture
– SPA routing & page modules (Landing, RoleSelect, AACPanel, GameScene, Presenter)
– WebSocketContext as the glue for real-time events
– Public/assets & public/audio as static content providers
– Strategy pattern files under src/game/moveStrategy
– server-backend’s role in session orchestration

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Browser"
        direction TB
        subgraph "React UI Layer"
            direction TB
            Landing["LandingPage"]:::frontend
            RoleSelect["RoleSelectPage"]:::frontend
            AACPage["AacPage"]:::frontend
            PhaserPage["PhaserPage"]:::frontend
            PresenterGame["PresenterGamePage"]:::frontend
            Presenter["PresenterPage"]:::frontend
            ButtonClick["ButtonClick"]:::frontend
            Leaderboard["Leaderboard"]:::frontend
            UserList["UserList"]:::frontend
            Router["Router"]:::frontend
            WebSocketContext["WebSocketContext"]:::frontend
            WebSocketClient["WebSocket Client"]:::frontend
        end
        subgraph "AAC Input Layer"
            direction TB
            AACInterface["AacInterface"]:::frontend
        end
        subgraph "Game Engine Layer"
            direction TB
            PhaserWrapper["PhaserGame"]:::frontend
            MainGameScene["GameScene"]:::frontend
            EventBus["EventBus"]:::frontend
            MovementStore["MovementStore"]:::frontend
            MoveStrategy["MoveStrategy"]:::frontend
            JumpStrategy["JumpStrategy"]:::frontend
            WalkStrategy["WalkStrategy"]:::frontend
            EdgeSlideStrategy["EdgeSlideStrategy"]:::frontend
            Hippo["Hippo"]:::frontend
            HippoTest["Hippo.test"]:::frontend
        end
    end

    subgraph "WebSocket Server"
        direction TB
        WS["WebSocket Server"]:::backend
        SessionManager["sessionAPI"]:::backend
        WS --> SessionManager
    end

    subgraph "Static Asset Host"
        direction TB
        ImageAssets["public/assets"]:::assets
        AudioAssets["public/audio"]:::assets
    end

    subgraph "CI/CD & Hosting"
        direction TB
        GitHubActions["GitHub Actions"]:::ci
        Vercel["Vercel Deploy"]:::ci
        GitHubPages["GitHub Pages"]:::ci
        Documentation["Docs Site (Docusaurus)"]:::ci
        GitHubActions --> Vercel
        GitHubActions --> GitHubPages
        GitHubPages --> Documentation
    end

    %% Connections
    Router -->|routes to| Landing
    Router --> RoleSelect
    Router --> AACPage
    Router --> PhaserPage
    Router --> PresenterGame
    Router --> Presenter
    AACInterface -->|control events| PhaserWrapper
    PhaserWrapper --> MainGameScene
    MainGameScene --> EventBus
    EventBus --> MovementStore
    MovementStore --> MoveStrategy
    MoveStrategy --> JumpStrategy
    MoveStrategy --> WalkStrategy
    MoveStrategy --> EdgeSlideStrategy
    MainGameScene --> Hippo
    HippoTest --> Hippo
    Landing -->|assetRequest| ImageAssets
    RoleSelect -->|assetRequest| ImageAssets
    PhaserWrapper -->|assetRequest| ImageAssets
    PhaserWrapper -->|assetRequest| AudioAssets
    WebSocketClient <-->|WebSocket| WS

    %% Click Events
    click Landing "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/LandingPage/LandingPage.tsx"
    click RoleSelect "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/RoleSelection/RoleSelect.tsx"
    click AACPage "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/AacPage/AacPage.tsx"
    click PhaserPage "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/PhaserPage/PhaserPage.tsx"
    click PresenterGame "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/PresenterGamePage/PresenterGame.tsx"
    click Presenter "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/pages/PresenterPage/Presenter.tsx"
    click ButtonClick "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/components/ButtonClick/ButtonClick.tsx"
    click Leaderboard "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/components/Leaderboard/Leaderboard.tsx"
    click UserList "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/components/UserList/UserList.tsx"
    click Router "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/router.tsx"
    click WebSocketContext "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/contexts/WebSocketContext.tsx"
    click AACInterface "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/aac/AacInterface.tsx"
    click PhaserWrapper "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/PhaserGame.tsx"
    click MainGameScene "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/scenes/Game.ts"
    click EventBus "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/EventBus.ts"
    click MovementStore "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/scenes/MovementStore.ts"
    click MoveStrategy "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/moveStrategy/MoveStrategy.ts"
    click JumpStrategy "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/moveStrategy/JumpStrategy.ts"
    click WalkStrategy "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/moveStrategy/WalkStrategy.ts"
    click EdgeSlideStrategy "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/EdgeSlideStrategy.ts"
    click Hippo "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/Hippo.ts"
    click HippoTest "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/src/game/Hippo.test.ts"
    click ImageAssets "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/tree/main/public/assets/"
    click AudioAssets "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/tree/main/public/audio/"
    click WS "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/server-backend/main.tsx"
    click SessionManager "https://github.com/capstone-projects-2025-spring/project-acc-hungry-hippos/blob/main/sessionAPI.js"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,stroke-width:2px
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef assets fill:#fff3cd,stroke:#ffcc00,stroke-width:2px
    classDef ci fill:#e2e3e5,stroke:#6c757d,stroke-width:2px
```
