# dendriel/princeps architecture

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

- Interactive diagram: https://gitdiagram.com/dendriel/princeps
- Repository: https://github.com/dendriel/princeps

## Overview

##### Project type and purpose
- This is a full-stack online multiplayer Memory Game.
- Client is a browser-based game built with Phaser and TypeScript.
- Server is an authoritative game server in TypeScript, using Socket.io (via Rozsa MOGS) for real-time communication.
- Shared package holds all message payload definitions and common types.

##### File structure
Top-level:
- assets, public: static assets (images, HTML, config).
- client.js, server-backend.js: entry points/scripts for deployment or local launch.
- packages/princeps-client: Phaser game client code.
- packages/server: Game server logic, command handlers, services.
- packages/shared: DTOs, command abstractions, shared types.
Patterns & configuration:
- Monorepo managed with package.json/workspaces.
- Each package has its own tsconfig.json.
- server/src/services implements game lifecycle (lobby, matchmaking, auto-shutdown).
- client/src/game-client handles incoming server commands and maps to game UI actions.

##### README for technical stack insights
- Frontend: Phaser (TypeScript), Rozsa MOGS over Socket.io.
- Backend: Node.js (TypeScript), Rozsa MOGS for websockets.
- Hosted on AWS (likely S3 + CloudFront for client, EC2/Lambda for server).
- No persistent database—state kept in memory, auto-shutdown service.

a. Main components to represent:
- Web Browser (Game UI)
‑ Phaser engine
‑ Chat Manager & UI components
‑ Command Dispatcher (turns server messages into UI updates)
- Shared Library (NPM workspace)
‑ Command and payload definitions (TypeScript interfaces)
- Game Server
‑ Rozsa MOGS / Socket.io layer
‑ Command Dispatcher → Handler modules (select-card, update-nickname, etc.)
‑ Services: lobby holder, matchmaking, match handler, auto-shutdown
- Static Hosting (AWS S3/CloudFront)
- AWS Compute (EC2 or Lambda hosting the server)

b. Relationships and data flow:
1. Browser requests index.html → static host → downloads client bundle & config.json.
2. Client initializes Phaser UI, connects to server via WebSocket.
3. Client-shared: client sends “client-command” (select-card, update-nickname) payload to server.
4. Server dispatches to appropriate handler, updates game state in memory, then emits “server-command” events.
5. Client receives server commands (e.g., show-card, update-score) → UI updates.
6. Optionally, chat messages flow through same WebSocket channel.

c. Architectural patterns and design principles:
- Command pattern: client and server both use command dispatchers and handlers.
- Monorepo modularity: shared code lives in a dedicated package to enforce strong typing across boundaries.
- In-memory stateful server with lifecycle services (lobby, matchmaking, auto-shutdown).
- Clear separation of concerns: game logic vs. networking vs. UI.

d. Relevant technologies:
- TypeScript throughout
- Phaser for game rendering/UI on client
- Rozsa MOGS (Socket.io wrapper) for communication
- Node.js runtime for server
- AWS hosting (S3, CloudFront, EC2/Lambda)
- JSON configuration (public/config.json, server services)

##### Elements
- Clear labels: e.g., “Game Client (Phaser)”, “WebSocket (Rozsa MOGS)”, “Game Server Command Dispatcher”.
– From Browser → Static Host (HTTP GET)
– From Browser ↔ Server (WebSocket full-duplex)
– Rectangles for components (Client, Server, Shared)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Browser)"
        direction TB
        GC["Game Client (Phaser Engine & UI)"]:::client
        UI["Client Game Objects & UI Components"]:::client
        Chat["Chat Manager & UI Components"]:::client
        CCD["Client Command Dispatcher"]:::client
        CCH["Client Command Handlers"]:::client
    end

    SL["Shared DTOs & Common Types"]:::shared

    subgraph "Server"
        direction TB
        SE["Game Server Entry Point"]:::server
        CI["Server Connection Info & Config"]:::server
        SCD["Server Command Dispatcher"]:::server
        ASH["Abstract Server Command Handler"]:::server
        SCH["Server Command Handlers"]:::server
        Services["Server Services (lobby, matchmaking, auto-shutdown)"]:::server
        MEM(("In-memory State")):::infra
    end

    subgraph "Hosting Infrastructure"
        direction TB
        Static["Static Hosting (AWS S3/CloudFront)"]:::infra
        Assets["Static Assets & Public Config"]:::infra
        Compute["AWS Compute (EC2/Lambda)"]:::infra
        Deployment["Deployment Scripts / Entry Points"]:::infra
    end

    WS["WebSocket (Rozsa MOGS over Socket.io)"]:::infra

    Assets -->|"HTTP GET index.html"| GC
    GC -->|"init Phaser & connect"| WS
    WS <--->|"full-duplex commands"| SCD
    GC -->|"uses types"| SL
    SCD -->|"uses types"| SL

    SE -->|"dispatches commands"| SCD
    CI --> SE
    Compute --> SE
    Deployment --> SE

    SCD --> ASH
    ASH --> SCH
    SCH --> Services
    Services --> MEM

    classDef client fill:#D0E8FF,stroke:#4A90E2
    classDef shared fill:#E5F5E0,stroke:#57A773
    classDef server fill:#FFE4CC,stroke:#E07A5F
    classDef infra fill:#F0F0F0,stroke:#9E9E9E

    click GC "https://github.com/dendriel/princeps/blob/master/packages/princeps-client/src/princeps-game-client.ts"
    click UI "https://github.com/dendriel/princeps/tree/master/packages/princeps-client/src/game"
    click Chat "https://github.com/dendriel/princeps/blob/master/packages/princeps-client/src/components/chat-manager.ts"
    click CCD "https://github.com/dendriel/princeps/blob/master/packages/princeps-client/src/game-client/commands/command-dispatcher.ts"
    click CCH "https://github.com/dendriel/princeps/tree/master/packages/princeps-client/src/game-client/command-handlers/"
    click SL "https://github.com/dendriel/princeps/tree/master/packages/shared/src"
    click SE "https://github.com/dendriel/princeps/blob/master/packages/server/src/princeps-server.ts"
    click CI "https://github.com/dendriel/princeps/blob/master/packages/server/src/princeps-connection-info.ts"
    click SCD "https://github.com/dendriel/princeps/blob/master/packages/server/src/commands/command-dispatcher.ts"
    click ASH "https://github.com/dendriel/princeps/blob/master/packages/server/src/commands/abstract-server-command-handler.ts"
    click SCH "https://github.com/dendriel/princeps/tree/master/packages/server/src/commands/handlers/"
    click Services "https://github.com/dendriel/princeps/tree/master/packages/server/src/services/"
    click Assets "https://github.com/dendriel/princeps/tree/master/public/"
    click Deployment "https://github.com/dendriel/princeps/blob/master/client.js"
```
