# neves-nvs/santorini architecture

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

- Interactive diagram: https://gitdiagram.com/neves-nvs/santorini
- Repository: https://github.com/neves-nvs/santorini

## Overview

##### Project Type and Purpose
- This is a full‐stack, real‐time, web-based implementation of the board game Santorini.
- Frontend: 3D rendering (Three.js + Vite + TypeScript) for interactive game play.
- Backend: Node.js + Express + WebSocket + Kysely (SQL ORM) + Passport.js for authentication, game logic enforcement, persistence, and real-time messaging.

##### File Structure
Top level:
- packages/client → all UI, rendering, network code
- packages/server → HTTP/WebSocket API, controllers, services, repositories, migrations, tests
- assets, blog, workflows, docs
Notice patterns:
- Client uses MVC-style separation (model, controller, view, services).
- Server uses layered architecture (controllers → services → repositories), plus Express middlewares and WebSocket handlers.
- Database migrations under server/migrations.
- Tests separated into unit vs integration (HTTP + WebSocket).

##### README for Additional Insights
- Technologies: Node.js, Express, Kysely (SQL), Passport.js, Three.js, TypeScript.
- Flow: User authenticates → engages a game session → all moves/updates exchanged over WebSocket → persisted in DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser)"
        subgraph "UI Layer"
            SceneMgr["SceneManager"]:::frontend
            BoardMgr["BoardManager"]:::frontend
            AudioMgr["AudioManager"]:::frontend
            InputMgr["InputManager"]:::frontend
            STLLoad["STLLoader"]:::frontend
        end
        subgraph "Controller Layer"
            GameCtrl["GameController"]:::frontend
            NetMgr["NetworkManager"]:::frontend
        end
        subgraph "Service Layer"
            AuthSvc["authService"]:::frontend
        end
        MainFE["Main.ts"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Node.js/Express)"
        subgraph "HTTP API" 
            AuthCtrl["authController"]:::backend
            UserCtrl["userController"]:::backend
            GameCtrlS["gameController"]:::backend
        end
        subgraph "WebSocket API"
            WSIndex["index.ts"]:::backend
            WSAuth["authenticatedWebsocket"]:::backend
            MsgHandler["messageHandler"]:::backend
        end
        subgraph "Authentication"
            PassportStrat["passport.ts"]:::backend
            WS_Strategy["webSocketAuth.ts"]:::backend
        end
        subgraph "Business Logic"
            GameSvc["gameService"]:::service
            GameSess["gameSession"]:::service
        end
        subgraph "Data Access"
            GameRepo["gameRepository"]:::backend
            PieceRepo["pieceRepository"]:::backend
            UserRepo["userRepository"]:::backend
            BoardModel["board.ts"]:::backend
        end
        subgraph "Middlewares"
            ErrMw["errorMiddleware"]:::backend
            LogMw["morganMiddleware"]:::backend
            GenMw["middleware.ts"]:::backend
        end
        subgraph "Config & Init"
            DBConf["database.ts"]:::backend
            Configs["config.ts"]:::backend
            Migrations["migrations"]:::db
            AppInit["app.ts"]:::backend
            MainSrv["main.ts"]:::backend
        end
    end

    %% External & Database
    DB["PostgreSQL (Kysely)"]:::db
    OAuth["OAuth Provider"]:::external

    %% Frontend Flows
    MainFE --> SceneMgr
    MainFE --> BoardMgr
    MainFE --> AudioMgr
    MainFE --> InputMgr
    MainFE --> STLLoad
    MainFE --> GameCtrl
    GameCtrl --> AuthSvc
    GameCtrl --> NetMgr

    NetMgr -->|"HTTP/JSON"| AuthCtrl
    NetMgr -->|"HTTP/JSON"| UserCtrl
    NetMgr -->|"HTTP/JSON"| GameCtrlS
    NetMgr <-->|"WS Messages"| WSIndex

    %% Backend Flows
    WSIndex --> WSAuth
    WSAuth --> WS_Strategy
    WSAuth --> MsgHandler
    MsgHandler --> GameSvc
    AuthCtrl --> PassportStrat
    AuthCtrl --> GenMw
    UserCtrl --> GenMw
    GameCtrlS --> GenMw

    GameSvc --> GameRepo
    GameSvc --> PieceRepo
    GameSvc --> UserRepo
    GameSvc --> GameSess
    GameSess --> GameSvc

    GameRepo --> DB
    PieceRepo --> DB
    UserRepo --> DB
    BoardModel --> DB

    AppInit --> GenMw
    AppInit --> LogMw
    AppInit --> ErrMw
    AppInit --> PassportStrat
    AppInit --> DBConf
    AppInit --> Configs
    MainSrv --> AppInit

    PassportStrat --> OAuth

    %% Click Events - Frontend
    click SceneMgr "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/view/SceneManager.ts"
    click BoardMgr "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/view/BoardManager.ts"
    click AudioMgr "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/view/AudioManager.ts"
    click InputMgr "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/view/InputManager.ts"
    click STLLoad "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/view/STLLoader.ts"
    click GameCtrl "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/controller/GameController.ts"
    click NetMgr "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/controller/NetworkManager.ts"
    click AuthSvc "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/services/authService.ts"
    click MainFE "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/Main.ts"
    click BlockType "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/model/BlockType.ts"
    click Player "https://github.com/neves-nvs/santorini/blob/main/packages/client/src/model/Player.ts"

    %% Click Events - Backend
    click AuthCtrl "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/auth/authController.ts"
    click UserCtrl "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/users/userController.ts"
    click GameCtrlS "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/game/gameController.ts"
    click WSIndex "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/websockets/index.ts"
    click WSAuth "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/websockets/authenticatedWebsocket.ts"
    click MsgHandler "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/websockets/messageHandler.ts"
    click WS_Strategy "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/auth/webSocketAuth.ts"
    click PassportStrat "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/auth/passport.ts"
    click GameSvc "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/game/gameService.ts"
    click GameSess "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/game/gameSession.ts"
    click GameRepo "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/game/gameRepository.ts"
    click PieceRepo "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/board/pieceRepository.ts"
    click UserRepo "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/users/userRepository.ts"
    click BoardModel "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/board/board.ts"
    click AppInit "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/app.ts"
    click MainSrv "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/main.ts"
    click ErrMw "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/middlewares/errorMiddleware.ts"
    click LogMw "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/middlewares/morganMiddleware.ts"
    click GenMw "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/middlewares/middleware.ts"
    click DBConf "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/database.ts"
    click Configs "https://github.com/neves-nvs/santorini/blob/main/packages/server/src/configs/config.ts"
    click Migrations "https://github.com/neves-nvs/santorini/tree/main/packages/server/migrations"

    %% Styles
    classDef frontend fill:#C3E0FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#D6F5D6,stroke:#28a745,color:#276749
    classDef service fill:#FFE4B3,stroke:#DD6B20,color:#8A4F01
    classDef db fill:#E2E2E2,stroke:#666666,color:#444444
    classDef external fill:#F0E6FF,stroke:#8A2BE2,color:#5D21A9
```
