# tjholm/multiboy architecture

> Architecture diagram of the GitHub repository tjholm/multiboy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tjholm/multiboy
- Repository: https://github.com/tjholm/multiboy

## Overview

##### Main Components

a. Client-Side (Browser):
- Astro Pages (host.astro, guest.astro, index.astro)
- Game Components (Controls.tsx, Countdown.tsx)
- State Management (stores folder - countdown, game, strategy, you)
- WebRTC Components (lib/spoke.ts, lib/hub.ts)
- GameBoy Emulator

b. Backend Services:
- Asset Management API
- WebSocket Signaling Server
- Database Resources (src/backend/resources/db.ts)

c. Cloud Infrastructure:
- AWS specific components defined in nitric.aws.yaml
- Database (DynamoDB or similar as indicated by db.ts)
- WebSocket API Gateway
- REST API Gateway

##### Connection Flows

a. WebRTC Peer-to-Peer Connections:
- Direct lines between clients for game state sharing
- That this is the primary game data channel

b. Signaling Flow:
- Lines from clients to WebSocket API for connection negotiation
- This is only for initial connection setup

c. Asset Management:
- RESTful communication between clients and backend API

##### Game Mode Representation

A small section showing the three game modes:
- Chaos Mode
- Shuffle Mode
- Hotseat Mode

##### Specific Implementation Details

Notes for:
- WebRTC peer connections (no TURN servers)
- State management flow using stores
- Game input handling system

**[Client Layer]**
- ↕
**[WebRTC P2P Layer]**
- ↕
**[Backend Services Layer]**
- ↕
**[Cloud Infrastructure Layer]**

Important Considerations:

##### How the emulator integrates with the input management system

- All component types
- Connection types (WebRTC, WebSocket, REST)
- Game mode indicators
- State flow markers

- How game inputs are shared between players
- How the signaling server facilitates connections
- How different game modes affect input handling
- The role of each store in state management

This architecture should clearly demonstrate the distributed nature of the application while highlighting the minimal backend requirements due to the P2P approach.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        FE[Frontend Layer]
        subgraph Pages
            HP["Host Interface"]:::page
            GP["Guest Interface"]:::page
            LP["Landing Page"]:::page
        end
        subgraph Components
            CI["Controls Interface"]:::component
            CD["Countdown Display"]:::component
            GS["Game Screen"]:::component
        end
        subgraph Stores
            CS["Countdown Store"]:::store
            GMS["Game Store"]:::store
            SS["Strategy Store"]:::store
            PS["Player Store"]:::store
        end
        subgraph WebRTC
            HUB["Hub"]:::webrtc
            SPOKE["Spoke"]:::webrtc
            IM["Input Manager"]:::webrtc
            MH["Message Handler"]:::webrtc
        end
        GB["GameBoy Emulator"]:::emulator
    end

    subgraph Backend
        SIG["Signaling Server"]:::backend
        DB["Database Handler"]:::backend
        MS["Main Server"]:::backend
        SR["Signal Resources"]:::backend
    end

    subgraph Infrastructure
        WSG["WebSocket Gateway"]:::infra
        RAG["REST API Gateway"]:::infra
        DDB["DynamoDB"]:::infra
    end

    subgraph GameModes
        CM["Chaos Mode"]:::mode
        SM["Shuffle Mode"]:::mode
        HM["Hotseat Mode"]:::mode
    end

    %% Connections
    FE --> Pages
    Pages --> Components
    Components --> Stores
    Components --> WebRTC
    WebRTC --> GB
    WebRTC <--> |P2P| WebRTC
    WebRTC --> SIG
    SIG --> WSG
    MS --> RAG
    DB --> DDB
    Stores --> GameModes

    %% Click Events
    click HP "https://github.com/tjholm/multiboy/blob/main/src/pages/host.astro"
    click GP "https://github.com/tjholm/multiboy/blob/main/src/pages/guest.astro"
    click LP "https://github.com/tjholm/multiboy/blob/main/src/pages/index.astro"
    click CI "https://github.com/tjholm/multiboy/blob/main/src/components/Controls.tsx"
    click CD "https://github.com/tjholm/multiboy/blob/main/src/components/Countdown.tsx"
    click GS "https://github.com/tjholm/multiboy/blob/main/src/components/Screen.astro"
    click HUB "https://github.com/tjholm/multiboy/blob/main/src/lib/hub.ts"
    click SPOKE "https://github.com/tjholm/multiboy/blob/main/src/lib/spoke.ts"
    click IM "https://github.com/tjholm/multiboy/blob/main/src/lib/input-manager.ts"
    click MH "https://github.com/tjholm/multiboy/blob/main/src/lib/messages.ts"
    click CS "https://github.com/tjholm/multiboy/blob/main/src/stores/countdown.ts"
    click GMS "https://github.com/tjholm/multiboy/blob/main/src/stores/game.ts"
    click SS "https://github.com/tjholm/multiboy/blob/main/src/stores/strategy.ts"
    click PS "https://github.com/tjholm/multiboy/blob/main/src/stores/you.ts"
    click SIG "https://github.com/tjholm/multiboy/blob/main/src/backend/signal.ts"
    click DB "https://github.com/tjholm/multiboy/blob/main/src/backend/resources/db.ts"
    click MS "https://github.com/tjholm/multiboy/blob/main/src/backend/server.ts"
    click SR "https://github.com/tjholm/multiboy/blob/main/src/backend/resources/signal.ts"

    %% Styles
    classDef page fill:#e1f5fe,stroke:#01579b
    classDef component fill:#e8f5e9,stroke:#2e7d32
    classDef store fill:#fff3e0,stroke:#ff6f00
    classDef webrtc fill:#f3e5f5,stroke:#7b1fa2
    classDef emulator fill:#fce4ec,stroke:#c2185b
    classDef backend fill:#efebe9,stroke:#3e2723
    classDef infra fill:#ede7f6,stroke:#4527a0
    classDef mode fill:#f1f8e9,stroke:#33691e
```
