# kevinshen56714/skyoffice architecture

> Architecture diagram of the GitHub repository kevinshen56714/skyoffice, 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/kevinshen56714/skyoffice
- Repository: https://github.com/kevinshen56714/skyoffice

## Overview

##### Project type and purpose
- SkyOffice is a full-stack, real-time virtual office application.
- Client side: browser game + React UI + Phaser3 + WebRTC for video/screen sharing.
- Server side: Node.js with Colyseus (WebSocket game‐room framework), maintaining in-memory room state.
- No traditional database; room state is managed by Colyseus schemas and commands.

##### File structure
- Top level:
- client/ → front-end code (Phaser scenes, React components, services, stores).
- server/ → back-end code (Colyseus rooms, state schema, update commands).
- types/ → shared TypeScript interfaces and enums.
- netlify.toml, Procfile → deployment configuration.
- client/src/services/Network.ts: WebSocket/Colyseus client.
- client/src/web/WebRTC.ts & ShareScreenManager.ts: PeerJS signaling and media streams.
- server/rooms/SkyOffice.ts: room logic, uses commands in server/rooms/commands/*.
- server/rooms/schema/OfficeState.ts: shared state model.

##### Extract architecture insights from README
- Reactive UI built with React/Redux.
- Phaser3 game engine for 2D map, character movement, proximity detection.
- Colyseus for real-time synchronization of map, chat bubbles, items, whiteboards.
- PeerJS for P2P video/screen streams (signaling via Colyseus).
- Whiteboard integration via an embedded iframe (WBO).

##### Main components
A. Front-End (Browser)
1. UI Layer (React/Redux)
- Components: ChatDialog, RoomSelectionDialog, CreateRoomForm, WhiteboardDialog, etc.
- Redux stores: ChatStore, RoomStore, UserStore, ComputerStore, WhiteboardStore.
2. Game Engine (Phaser3)
- Scenes: Bootstrap → Game → Background
- Characters & Items: MyPlayer, OtherPlayer, Chairs, Computers, VendingMachine, Whiteboard.
- Animations and assets loader.
3. Networking Layer
- Colyseus client connection (Network.ts)
- EventCenter.ts for dispatching received server messages
4. WebRTC Layer (PeerJS)
- PeerJS signaling through Colyseus channels
- Media management: ShareScreenManager, WebRTC.ts

B. Back-End (Node.js + Colyseus)
1. Colyseus Server
- Room handler: SkyOffice (creates/manages player sessions)
- Commands: ChatMessageUpdateCommand, PlayerUpdateCommand, WhiteboardUpdateArrayCommand, etc.
- Schema: OfficeState (users, positions, items, whiteboard data).
2. WebSocket Transport
- Colyseus networking over WS → handles join, leave, patch broadcasts
3. Signaling for WebRTC
- Uses the same Colyseus channel to exchange PeerJS offers/answers

C. External Services
- Whiteboard: iframe embedding WBO (Open-source whiteboard)
- PeerJS cloud or self-hosted signaling server (optional)

##### Relationships & data flows
- User input (keyboard/mouse) → Phaser3/React → triggers local state changes & updates Network.ts
- Network.ts → sends room commands (join, move, chat, whiteboard) via WebSocket to Colyseus
- Colyseus server receives commands → validates & applies to OfficeState → broadcasts patches to all clients
- Client EventCenter receives patches → updates Redux stores & Phaser scenes
- When two players are in proximity, client WebRTC layer negotiates P2P via PeerJS, using Colyseus for signaling
- WhiteboardDialog uses iframe → communicates with WBO REST/WS endpoints

##### Architectural patterns & principles
- Real-time event-driven architecture (commands & patches)
- Separation of concerns: UI vs. game engine vs. network vs. media layer
- Single‐page application with client‐side routing (React)
- Command pattern on server side for state mutations
- Shared TypeScript interfaces (in types/) for end-to-end type safety

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Browser Client"
        subgraph "UI Layer"
            App["App.tsx"]:::frontend
            Components["React Components"]:::frontend
        end
        subgraph "Redux Stores"
            Stores["ChatStore, RoomStore, UserStore, ComputerStore, WhiteboardStore"]:::frontend
        end
        subgraph "Phaser Game"
            PG["PhaserGame.ts"]:::game
            subgraph "Scenes"
                BS["Bootstrap.ts"]:::game
                GA["Game.ts"]:::game
                BG["Background.ts"]:::game
            end
            subgraph "Characters"
                Chars["MyPlayer, OtherPlayer, Player, PlayerSelector"]:::game
            end
            subgraph "Items"
                Items["Chair, Computer, VendingMachine, Whiteboard, Item"]:::game
            end
            Anim["CharacterAnims.ts"]:::game
        end
        subgraph "Networking Layer"
            Net["Network.ts"]:::network
            Event["EventCenter.ts"]:::network
        end
        subgraph "WebRTC Layer"
            WRTC["WebRTC.ts"]:::media
            SS["ShareScreenManager.ts"]:::media
        end
        subgraph "Whiteboard"
            WBIF["Whiteboard iframe"]:::external
        end
    end

    subgraph "Colyseus Server"
        Entry["server/index.ts"]:::backend
        Room["SkyOffice.ts"]:::backend
        Cmds["commands (ChatMessageUpdateCommand, PlayerUpdateCommand, etc.)"]:::backend
        Schema["OfficeState.ts"]:::backend
    end

    subgraph "External Services"
        PeerJS["PeerJS Server"]:::external
        WBO["WBO Whiteboard (WBO)"]:::external
    end

    %% Data Flows
    Components -->|"user input"| PG
    Components -->|"UI actions"| Net
    App -->|"renders components"| Components
    Net -->|"join/move/chat commands"| Entry
    Entry -->|"handle session"| Room
    Room -->|"uses schema"| Schema
    Room -->|"invokes"| Cmds
    Room -->|"broadcast statePatch"| Entry
    Entry -->|"statePatch"| Net
    Net -->|"patch events"| Event
    Event -->|"update"| Stores
    Stores -->|"state change"| Components
    PG -->|"update scenes"| BS & GA & BG
    BS & GA & BG -->|"render characters/items"| PG
    PG -->|"animation data"| Anim
    WRTC -->|"SDP Offer/Answer via Colyseus"| Net
    Net -->|"signal"| PeerJS
    PeerJS -->|"signal"| Net
    Net -->|"deliver signal"| WRTC & SS
    Components -->|"open whiteboard"| WBIF
    WBIF -->|"communicate"| WBO

    %% Click Events
    click Components "https://github.com/kevinshen56714/skyoffice/tree/master/client/src/components"
    click Stores "https://github.com/kevinshen56714/skyoffice/tree/master/client/src/stores"
    click App "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/App.tsx"
    click PG "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/PhaserGame.ts"
    click BS "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/scenes/Bootstrap.ts"
    click GA "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/scenes/Game.ts"
    click BG "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/scenes/Background.ts"
    click Chars "https://github.com/kevinshen56714/skyoffice/tree/master/client/src/characters"
    click Items "https://github.com/kevinshen56714/skyoffice/tree/master/client/src/items"
    click Anim "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/anims/CharacterAnims.ts"
    click Net "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/services/Network.ts"
    click Event "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/events/EventCenter.ts"
    click WRTC "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/web/WebRTC.ts"
    click SS "https://github.com/kevinshen56714/skyoffice/blob/master/client/src/web/ShareScreenManager.ts"
    click types "https://github.com/kevinshen56714/skyoffice/tree/master/types"
    click Entry "https://github.com/kevinshen56714/skyoffice/blob/master/server/index.ts"
    click Room "https://github.com/kevinshen56714/skyoffice/blob/master/server/rooms/SkyOffice.ts"
    click Cmds "https://github.com/kevinshen56714/skyoffice/tree/master/server/rooms/commands"
    click Schema "https://github.com/kevinshen56714/skyoffice/blob/master/server/rooms/schema/OfficeState.ts"
    click netlify "https://github.com/kevinshen56714/skyoffice/blob/master/netlify.toml"
    click Procfile "https://github.com/kevinshen56714/skyoffice/tree/master/Procfile"
    click HTML "https://github.com/kevinshen56714/skyoffice/blob/master/client/index.html"
    click Assets "https://github.com/kevinshen56714/skyoffice/tree/master/client/public/assets"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#8884FF,color:#000
    classDef game fill:#D0FFD6,stroke:#00A000,color:#000
    classDef network fill:#FFE0B2,stroke:#FF9800,color:#000
    classDef media fill:#E1BEE7,stroke:#9C27B0,color:#000
    classDef external fill:#E0E0E0,stroke:#757575,color:#000
    classDef backend fill:#FFCDD2,stroke:#D32F2F,color:#000
```
