# frozenlabs/neocinema architecture

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

- Interactive diagram: https://gitdiagram.com/frozenlabs/neocinema
- Repository: https://github.com/frozenlabs/neocinema

## Overview

##### Project Type and Purpose
- NeoCinema is a hybrid Minecraft mod/plugin project. It consists of:
a. A Fabric-based client mod (“fabric” sub-project) that runs in players’ game clients.
b. A Bukkit/Spigot plugin (“bukkit” sub-project) that runs on the game server.
- Purpose: Enable synchronized video playback (YouTube, Twitch, files) inside Minecraft, with queue/history, custom cinema blocks, and configurations.

##### Core Components
2.1 Fabric (Client)
- Mixins & Core Classes
– NeoCinema.java, NeoCinemaClient.java
– MixinMinecraftClient, MixinInGameHud, MixinClientPlayerEntity
- GUI & Screens
– VideoQueueScreen, VideoHistoryScreen, VideoSettingsScreen
– Widget classes (VideoListWidget, VideoQueueWidget, etc.)
- Network Layer
– Codecs (IdCodec), Payloads (inbound/outbound) under fabric/network
- Rendering & Blocks
– PreviewScreenBlock, ScreenBlock & corresponding EntityRenderers
- Utilities & Playback
– DependencyDownloader, NetworkUtil, PlaybackStatusHudUtil, etc.
– VideoLanPlayback for LAN streaming
- Settings & Data Managers
– NeoCinemaSettings, VideoListManager, VideoQueue

2.2 Bukkit (Server)
- Plugin Core
– NeoCinemaPlugin.java, NeoCinemaConfig.java
- Command Handlers & Executors
– VolumeCommand, HistoryCommand, RequestCommand, TheaterCommandExecutor, etc.
- Event Framework
– Custom events (PlayerEnterTheaterEvent, TheaterStartVideoEvent, etc.)
– Queue events under event/queue
- Theater & Queue Management
– TheaterManager, Theater classes (Public, Private, Static)
– VideoQueue, VideoRequest, VideoInfo, QueueVoteType
- Storage Layer
– Abstracted via SQLDriver, MySQLDriver, SQLiteDriver
– VideoStorage, TheaterStorage, RelationalVideoInfo, RelationalVideoRequest
- Service & Info Fetchers
– VideoURLParser, VideoInfoFetcher implementations (YouTube, Twitch, HLS, File)
- Buffer & Serialization
– PacketByteBufReimpl, PacketByteBufSerializable (for custom packet content)
- Tasks & Utilities
– PlayerListUpdateTask, ChatUtil, NetworkUtil, ProtocolLibUtil, VaultUtil

2.3 External Systems
- LibVLC / VLC media player (native library)
- External Video Services (YouTube API, Twitch API, HLS endpoints, HTTP file hosts)
- SQL Database (MySQL or SQLite)

##### Interactions & Data Flow
- Client → Server:
- Network payloads over Minecraft’s custom channels (outbound request: ChannelVideoRequestPayload)
- Command inputs from players trigger plugin commands via chat or GUI actions.
- Server:
1. Command/Event handling → TheaterManager & VideoService
2. VideoInfoFetcher fetches metadata from external video sources
3. Storage layer persists/retrieves queue & history in DB
4. LibVLC invoked (JNI or external process) to stream video data or metadata
5. Server broadcasts playback state updates (ChannelVideoQueueStatePayload, UpdatePreviewScreenPayload)
- Server → Client:
- Video frame updates or timeline commands via playback HUD utilities
- Client:
- Mixins alter HUD & input handling
- GUI screens render video queue/history and capture user actions
- VideoLanPlayback handles local playback streams

##### Architectural Patterns & Principles
- Modular separation: client vs. server codebases under separate Gradle subprojects
- Event-driven design on server (custom event classes & listeners)
- Command pattern for user-triggered actions
- Strategy/Factory for VideoInfoFetcher implementations
- Adapter pattern for SQL drivers (MySQL vs SQLite)
- Custom serialization layer for network packets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Fabric Client Module
    subgraph "Fabric Client Module"
        direction TB
        FabricCore["NeoCinema.java / NeoCinemaClient.java"]:::client
        FabricMixins["Mixins\n(MixinMinecraftClient, InGameHud, ClientPlayerEntity)"]:::client
        FabricGUI["GUI & Screens\n(VideoQueueScreen, VideoHistoryScreen, VideoSettingsScreen)"]:::client
        Widgets["Widgets\n(VideoListWidget, VideoQueueWidget, etc.)"]:::client
        FabricNetwork["Network Layer"]:::client
        FabricCodecs["Codecs\n(IdCodec)"]:::client
        FabricPayloads["Payloads\n(inbound/outbound)"]:::client
        FabricRendering["Rendering & Blocks\n(ScreenBlock, PreviewScreenBlock, EntityRenderers)"]:::client
        FabricUtilities["Utilities\n(DependencyDownloader, NetworkUtil, PlaybackStatusHudUtil, etc.)"]:::client
        VideoLanPlayback["VideoLanPlayback\n(LAN streaming)"]:::client
        Settings["Settings\n(NeoCinemaSettings)"]:::client
        VideoList["VideoListManager & VideoQueue"]:::client
    end

    %% Minecraft Engine
    Engine["Minecraft Engine\n(custom plugin channels)"]:::engine

    %% Bukkit Server Plugin
    subgraph "Bukkit Server Plugin"
        direction TB
        PluginCore["NeoCinemaPlugin.java / NeoCinemaConfig.java"]:::server
        Commands["Commands & Executors\n(Volume, History, Request, TheaterExecutor)"]:::server
        Events["Event Framework\n(PlayerEnterTheaterEvent, TheaterStartVideoEvent, etc.)"]:::server
        TheaterQueue["Theater & Queue Management\n(TheaterManager, Public/Private/StaticTheater, VideoQueue, QueueVoteType)"]:::server
        StorageLayer["Storage Layer\n(SQLDriver, MySQLDriver, SQLiteDriver,\nVideoStorage, TheaterStorage)"]:::server
        InfoFetchers["VideoInfoFetchers\n(YouTube, Twitch, HLS, File)"]:::server
        Buffer["Buffer & Serialization\n(PacketByteBufReimpl, PacketByteBufSerializable)"]:::server
        Tasks["Tasks & Utilities\n(PlayerListUpdateTask, ChatUtil, NetworkUtil, ProtocolLibUtil, VaultUtil)"]:::server
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DB["SQL Database\n(MySQL / SQLite)"]:::external
        VLC["LibVLC (native)"]:::external
        Services["Video Services\n(YouTube API, Twitch API, HLS, HTTP)"]:::external
    end

    %% Data Flows
    FabricGUI -->|"Player Action"| FabricNetwork
    FabricNetwork -->|"ChannelVideoRequestPayload"| Engine
    Engine -->|"PluginMessage"| PluginCore
    PluginCore -->|"dispatch to Commands/Events"| Commands
    Commands -->|"Event Trigger"| Events
    Events -->|"manage queue"| TheaterQueue
    TheaterQueue -->|"SQL Query"| StorageLayer
    StorageLayer -->|"data"| TheaterQueue
    Commands -->|"fetch info"| InfoFetchers
    InfoFetchers -->|"HTTP fetch"| Services
    PluginCore -->|"invoke JNI"| VLC
    TheaterQueue -->|"broadcast state"| Buffer
    Buffer -->|"ChannelVideoQueueStatePayload"| Engine
    Engine -->|"payload"| FabricNetwork
    FabricNetwork -->|"update GUI"| FabricGUI

    %% Click Events for Fabric
    click FabricCore "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/NeoCinema.java"
    click FabricCore "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/NeoCinemaClient.java"
    click FabricMixins "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/mixins"
    click FabricGUI "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/gui/VideoQueueScreen.java"
    click FabricGUI "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/gui/VideoHistoryScreen.java"
    click FabricGUI "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/gui/VideoSettingsScreen.java"
    click Widgets "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/gui/widget"
    click FabricNetwork "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/network"
    click FabricCodecs "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/network/codec/IdCodec.java"
    click FabricPayloads "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/network/payload/inbound"
    click FabricPayloads "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/network/payload/outbound"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/preview/PreviewScreenBlock.java"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/preview/PreviewScreenBlockEntity.java"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/preview/PreviewScreenBlockEntityRenderer.java"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/screen/ScreenBlock.java"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/screen/ScreenBlockEntity.java"
    click FabricRendering "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/block/screen/ScreenBlockEntityRenderer.java"
    click FabricUtilities "https://github.com/frozenlabs/neocinema/tree/dev/fabric/src/main/java/com/neocinema/fabric/util"
    click VideoLanPlayback "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/video/playback/VideoLanPlayback.java"
    click Settings "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/settings/NeoCinemaSettings.java"
    click VideoList "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/video/list/VideoListManager.java"
    click VideoList "https://github.com/frozenlabs/neocinema/blob/dev/fabric/src/main/java/com/neocinema/fabric/video/queue/VideoQueue.java"

    %% Click Events for Bukkit
    click PluginCore "https://github.com/frozenlabs/neocinema/blob/dev/bukkit/src/main/java/com/neocinema/bukkit/NeoCinemaPlugin.java"
    click PluginCore "https://github.com/frozenlabs/neocinema/blob/dev/bukkit/src/main/java/com/neocinema/bukkit/NeoCinemaConfig.java"
    click Commands "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/command"
    click Events "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/event"
    click Events "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/event/queue"
    click TheaterQueue "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/theater"
    click TheaterQueue "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/video/queue"
    click StorageLayer "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/storage"
    click StorageLayer "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/storage/sql"
    click InfoFetchers "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/service/infofetcher"
    click Buffer "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/buffer"
    click Tasks "https://github.com/frozenlabs/neocinema/blob/dev/bukkit/src/main/java/com/neocinema/bukkit/task/PlayerListUpdateTask.java"
    click Tasks "https://github.com/frozenlabs/neocinema/tree/dev/bukkit/src/main/java/com/neocinema/bukkit/util"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#1E90FF,color:#000
    classDef server fill:#DFFFE0,stroke:#32CD32,color:#000
    classDef engine fill:#EEEEEE,stroke:#888,color:#000
    classDef external fill:#FFE4B5,stroke:#FF8C00,color:#000
```
