Architecture Overview

This document explains the conceptual architecture of the Roblox Audio Bulk Uploader ecosystem.

For detailed file-level documentation, refer to the Project Structure. For API specifications, refer to the Bridge API Reference.

1. The Three Main Layers

The ecosystem consists of three distinct layers working together:

1. The Python Desktop App: The local application where the user prepares audio, mixes it, and initiates the upload.
2. Roblox Open Cloud API: Roblox's official web API that receives the audio files and manages moderation and permissions.
3. The Sync Ecosystem (Optional): A separate Node.js bridge server and an in-game Lua module that automatically push approved audio into your live Roblox experience's DataStore.

2. The Core Upload Flow

The following diagram illustrates the complete lifecycle of an audio batch from the user's computer to the live Roblox DataStore.

flowchart TD
    A[Python App] -->|Upload via Open Cloud| B[Roblox Servers]
    B --> C{Moderation Review}
    
    C -->|Approved| D[Auto-Grant Permissions]
    C -->|Rejected| E[Queue Halts]
    
    D -.->|Optional DataStore Sync POST| F[Bridge Server]
    F -.->|Polled via GET| G[Roblox Lua Module]
    G -.->|Writes to| H[(Roblox DataStore)]

3. Python Application Structure

The desktop client is built on a modular, event-driven architecture:

• GUI Layer: Built with CustomTkinter for a modern, dark-mode native interface.
• Handler Layer (Mixins): The UI logic is decoupled from the main window using specialized Mixin classes that handle specific domains (like drag-and-drop, configuration, and API queue management).
• Audio DSP Pipeline: Powered by pedalboard, which handles speed/pitch shifting, gain staging, peak limiting, and OGG Vorbis encoding.
• API Wrapper: The roblox_api.py module manages the asynchronous x-api-key communication with Roblox Open Cloud, handling rate limits and structured responses.
• Local State: The app maintains lightweight local state without a database. Upload logs are kept in upload_history.json, ongoing moderation polling is tracked in pending_moderation.json, and sensitive credentials (like the API key) are securely stored via the OS-level keyring.

4. The Bridge Server

When Owner Mode (DataStore Sync) is enabled, the Python app needs a way to communicate with your live Roblox server. Because Roblox servers cannot accept incoming HTTP requests directly, a middleman is required.

The Bridge Server is a lightweight Node.js HTTP service.

• It accepts authenticated POST payloads from the Python app containing metadata for newly approved audio assets.
• It securely holds this data in memory (or Redis, depending on your implementation).
• It serves a GET endpoint for the live Roblox game to poll.

5. The Lua Integration

Inside your live Roblox experience, the LiveMusicIngestion.luau module pulls the ecosystem together.

• It continuously polls the Bridge Server's GET endpoint for new audio data.
• It deduplicates incoming tracks based on their AudioId to prevent spam or overlap.
• It writes the final payload into the game's DataStore so that in-game scripts (like a DJ panel or radio system) can access the new music.

Important Initialization Note: This Lua module relies on the Knit framework but must be manually initialized via MusicService:KnitStart().

Note: The source code for the LiveMusicIngestion.luau module and the custom DataStore implementation are specific to your Roblox experience and are not included in this Python/Node repository tree.