RT Commission Dashboard
Multi-tier Sales & Commission Tracking Dashboard
A high-performance commission dashboard for managing affiliate networks with hierarchical commission structures. Built with NiceGUI and Python.
🚀 Features
- Multi-tier Commission System: Automatic commission calculation across unlimited hierarchy levels
- Volume-based Tier Ranking: Dynamic commission rates based on monthly sales performance
- Admin Panel: User management, financial oversight, and system settings
- Affiliate Tools: Network tree visualization, commission tracking, and shared sales
- Dual Backend Support:
- SQLite: Zero-setup local database (default)
- Supabase: Cloud PostgreSQL for production deployments
- Bilingual: Full support for English and Vietnamese (EN/VI)
🛠️ Installation & Usage
Quick Start (Recommended)
Run directly with uvx (no installation needed):
# SQLite (local database)
uvx rt-commission-dashboard --ui --port 8000
# Supabase (cloud database)
uvx rt-commission-dashboard --ui --port 8000 \
--db-type supabase \
--supabase-url https://your-project.supabase.co \
--supabase-anon-key your-anon-key \
--supabase-service-key your-service-key
For Development
# Clone and install
git clone https://github.com/rtavytran/rt-commission-dashboard.git
cd rt-commission-dashboard
uv sync
# Run locally
uv run rt-commission-dashboard --ui
⚙️ Configuration
Command-Line Arguments
| Argument | Description | Default |
|---|---|---|
--port |
Port to run the dashboard | 8000 |
--ui |
Start the web UI | - |
--db-type |
Database type: sqlite or supabase |
sqlite |
--supabase-url |
Supabase project URL | - |
--supabase-anon-key |
Supabase anonymous key | - |
--supabase-service-key |
Supabase service role key | - |
Configuration File
Optional: Create config.yaml to customize workspace settings, commission tiers, and application behavior. See config.yaml for the full template.
Admin Settings Page
Administrators can configure database settings through the web UI:
- Login as admin (
admin@rt.local) - Navigate to Settings in the admin menu
- Configure Supabase credentials or switch database types
🔐 Default Login
The dashboard comes with a pre-configured admin account for testing:
- Email:
admin@rt.local - Password: Any password (authentication is simplified for Phase 1)
Access the dashboard at http://localhost:8000 after starting the application.
💰 Financial Mechanics
The system implements a configurable Multi-Tier Automatic Commission structure triggered by retail_sales.
Volume-Based Commission Tiers
Commission rates are determined by Total Monthly Sales (Personal + F1).
| Monthly Sales | Rate |
|---|---|
| > 0 | 20% |
| > 200M | 22% |
| > 400M | 25% |
| > 1B | 30% |
| > 2B | 35% |
Differential Bonus (Stateful)
The system uses a Stateful Monthly Recalculation model.
- Step 1: Every
retail_salestransaction triggers a recalculation of the user's monthly volume and tier. - Step 2: The update propagates up the upline.
- Step 3: Upline earns the Differential between their Tier Rate and the Downline's Tier Rate.
- Benefit: Ensures "End-of-Month" consistency in real-time. If a user ranks up late in the month, their commission for the entire month is adjusted.
Note: Commission rates can be customized in config.yaml
Shared Opportunity
- Mechanism: A sale can be shared between two users (the "Sharer" who brings the opportunity and the "Receiver" who executes the sale).
- Volume for Tier Ranking: The FULL sales amount counts toward the Sharer's tier ranking. The Receiver gets 0% volume credit for tier ranking.
- Commission Split: Both parties earn commission on 50% of the sale value using their respective tier rates.
- Sharer: Commission = (Sharer's Tier Rate) × 50% × Sale Amount
- Receiver: Commission = (Receiver's Tier Rate) × 50% × Sale Amount
Inactive User Policy
- Definition: Users with 0 Personal Sales in the current month.
- Rate: They earn a fixed 4% commission on sales (and 4% receive/share rate) instead of the standard tier rates.
- Motivation: Encourages active selling to unlock higher tier rates (20%+).
Transaction Types
- Retail Revenue: Direct sales (Count towards Personal Revenue).
- Commission: Passive income (Count towards Total Income).
- Rewards: KPI Bonuses (Manual/Periodical).
📚 Documentation & Resources
- CHANGELOG.md: Version history and release notes
- spec/dashboard_spec.md: Full architecture and system requirements
- User Guides:
🛠️ Development
Setting Up Supabase (Optional)
If you want to use Supabase instead of SQLite:
- Create a project at supabase.com
- Get your project credentials from Settings → API
- Run the SQL schema from
spec/supabase_schema.sqlin the SQL editor - Use the
--supabase-*arguments when starting the dashboard
Running Tests
uv run pytest tests/
📦 PyPI Package
Published on PyPI: rt-commission-dashboard
pip install rt-commission-dashboard
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙋 Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Built with ❤️ by RealTimeX Team
1 maintainer
Metadata
1 maintainer
Release files for rt-commission-dashboard 1.2.27
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| rt_commission_dashboard-1.2.27.tar.gz | 47.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| rt_commission_dashboard-1.2.27-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 107.5 kB
Release files / rt_commission_dashboard-1.2.27.tar.gz
| Download URL | rt_commission_dashboard-1.2.27.tar.gz |
|---|---|
| Size | 47.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
37925541a118a0df67752c6f52569cf51a70fc44e15ade899616a2402e9d1d99
|
|
BLAKE2b-256 checksum How to use checksums |
bc83660ab21fc97050e6680d4356adb1b9126e1c4aaee4f6135300dfa5a3fc11
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / rt_commission_dashboard-1.2.27-py3-none-any.whl
| Download URL | rt_commission_dashboard-1.2.27-py3-none-any.whl |
|---|---|
| Size | 60.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9f830ab2e833fe7acb37d619123ace6939d5b8bedd8b3725a3a8d12e312ac47
|
|
BLAKE2b-256 checksum How to use checksums |
6bba183b9a95664f520ffa4618957b2eb1f6a9d0d7aeb5dc04b08bca1d144c38
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
