FluxLoad (Python Engine)

High-performance, minimalist file sharing server engineered with strict security boundaries, clean aesthetics, and dual-engine architecture (Python & Java).

Architectural Overview

FluxLoad operates across two specialized branches designed for distinct deployment needs:

Branch Navigation

# Clone the repository
git clone https://github.com/muadzhdz/fluxload.git
cd fluxload

# Switch to the Python engine (current branch)
git checkout python

# Switch to the Java engine
git checkout java

Key Features

• Unified File Explorer: Single-view table explorer with top navigation bar, dynamic breadcrumbs, and instant client-side file search.
• Whole-Page Drag-and-Drop: Drop files anywhere on the browser window to trigger instant uploads.
• Floating Upload Toast: Non-intrusive bottom-right progress monitor with real-time percentage, transfer stats, and cancel support.
• Rigorous Path Traversal Protection: Component-based path resolution (os.path.commonpath) eliminating directory traversal and sibling directory attacks.
• Root Directory Protection: Safeguards preventing accidental or malicious deletion of the root upload directory.
• REST API Parity: Unified /api/files endpoints enabling any frontend, script, or mobile client to interface interchangeably with Python or Java backends.
• 15 Built-in Developer Themes: Tokyo Night, Catppuccin (Mocha, Macchiato, Frappe, Latte), Rose Pine, Nord, Dracula, Gruvbox, and more.

Quick Start

Installation

# Clone the repository
git clone https://github.com/muadzhdz/fluxload.git
cd fluxload

# Install in editable mode
pip install -e .

Running the Server

# 1. Simple file server
fluxload-simple -d /path/to/share -p 8000

# Or via Python module directly:
python -m fluxload -d /path/to/share -p 8000

# Run with password protection
python -m fluxload -d /path/to/share --password mysecret

# 2. Enterprise server (Database, Whoosh search, WebSocket)
python -m fluxload.advanced_main -d /path/to/share

CLI Arguments

Docker Deployment

# Build the container
make docker-build

# Run the container
make docker-run

Or using standard Docker CLI:

docker build -t fluxload:python .
docker run -d -p 5000:5000 -v /my/files:/data fluxload:python

REST API Contract

Developer Workflow

# Display help and available tasks
make help

# Run test suite with coverage
make test

# Build and run Docker container
make docker-build
make docker-run

# Clean build artifacts
make clean

Zero-Emoji & Clean Design Policy

FluxLoad enforces a strict Zero-Emoji policy across all branches. User interfaces utilize Google Material Icons exclusively, and terminal outputs rely on clean, deterministic ASCII tags ([*], [+], [!], [ERROR]). Automated CI pipelines verify zero emoji violations on every commit and pull request.

Contributing

1. Review the engineering standards outlined in the Pull Request Template.
2. Ensure all unit tests pass (make test).
3. Ensure zero emoji characters exist anywhere in code, markdown, or commits.
4. Submit PR targeting either python or java branch.

License

This project is licensed under the MIT License. See LICENSE for details.