Skip to content

PROJECT_SETUP.md

Latest commit

 

History

History
356 lines (282 loc) · 10 KB

PROJECT_SETUP.md

File metadata and controls

356 lines (282 loc) · 10 KB

NetBoozt - Project Configuration Summary

✅ Completed Setup

📁 Project Structure

NetBoozt/
├── windows/              # Windows module (completed)
│   ├── src/
│   │   ├── gui/         # ttkbootstrap GUI
│   │   └── optimizations/ # 15+ TCP/IP optimizations
│   ├── tests/
│   ├── run.py
│   └── requirements.txt
├── linux/               # Linux module (structure ready)
├── docs/
│   ├── assets/
│   │   └── logo/       # LOUST logo + favicons (46 KB total)
│   ├── diagrams/       # Mermaid architecture
│   ├── optimizations/  # Detailed docs
│   │   ├── tcp-congestion-control.md
│   │   └── bbr-vs-cubic.md
│   ├── FAQ.md
│   └── ASSET_HOSTING.md
├── tools/              # Dev tools (gitignored)
│   ├── create_favicon.py
│   └── generate_screenshots.py
├── .github/
│   └── workflows/
│       ├── ci.yml      # GitHub Actions CI
│       └── release.yml # Auto-release
├── README.md           # English (main)
├── README.es.md        # Spanish
├── CONTRIBUTING.md
├── CHANGELOG.md
├── pyproject.toml
├── .gitignore
├── .pre-commit-config.yaml
└── init-git.ps1        # Git initialization script

🎨 Branding & Assets

Logo Configuration

  • Source: G:\loust-pro-agency\Presskit\LGOLST_WHITE.png
  • Copied to: docs/assets/logo/LGOLST_WHITE.png (24.6 KB)
  • App Icon: docs/assets/logo/netboozt_icon.png (10 KB)
  • Favicon: docs/assets/logo/favicon.ico + 6 PNG sizes

Favicon Sizes Generated

  • ✅ 16x16px (browser tab)
  • ✅ 32x32px (taskbar)
  • ✅ 48x48px (desktop)
  • ✅ 64x64px (high DPI)
  • ✅ 128x128px (retina)
  • ✅ 256x256px (Windows tile)

Total size: ~46 KB (safe for Git)

🌍 Internationalization (i18n)

Documentation Language Strategy

File Type Language Rationale
Code (.py) English International standard
Comments English Code should be globally readable
Variable names English Best practice
Main docs English Primary audience
Localized docs Spanish/Others README.es.md, etc.

Implemented

  • ✅ README.md - English (primary)
  • ✅ README.es.md - Spanish localization
  • ✅ Language switcher in README header
  • ✅ All code comments in English
  • ✅ CONTRIBUTING.md bilingual structure ready
  • ✅ docs/es/FAQ.md - Spanish FAQ
  • ✅ docs/es/bbr-vs-cubic.md - Spanish technical docs

Future i18n

  • docs/es/INSTALL.md - Spanish installation guide
  • docs/es/QUICKSTART.md - Spanish quick start
  • docs/pt-BR/ for Portuguese
  • docs/zh-CN/ for Chinese
  • GUI language selector (v1.2.0)

Strategy:

  • User-facing docs (README, FAQ, technical explanations): Multilingual
  • Developer docs (CONTRIBUTING, API, code): English only
  • Code (Python files): English only (international standard)

📧 Contact Information

Updated Emails

Applied in Files

🖼️ Asset Hosting Strategy

Git Repository (Committed)

What: Small assets < 100KB

  • ✅ Logos (LGOLST_WHITE.png, netboozt_icon.png)
  • ✅ Favicons (all sizes)
  • ✅ Diagrams (Mermaid .md files)

Why: Version controlled, always available

VPS Hosting (Recommended)

What: Medium/large assets > 100KB

  • Screenshots (future: when generate_screenshots.py runs)
  • Videos (demos, tutorials)
  • High-res media

Server: vps.loust.pro:999 (SSH tunnel) Path: /home/netboozt-assets/ URL: https://vps.loust.pro:999/netboozt/assets/

Upload command:

scp -P 999 -r docs/assets/screenshots/* user@vps.loust.pro:/home/netboozt-assets/screenshots/

Gitignored (Not Committed)

  • ❌ tools/ - Development scripts (favicon generator, screenshot automation)

    • Why: Internal dev tools, not needed by end users
    • Type: Code for maintainers only
    • Alternative: Document how to use in tools/README.md (committed)

  • ❌ docs/assets/screenshots/ - Auto-generated GUI captures

    • Why: Large files, frequently updated
    • Type: Marketing/documentation assets
    • Alternative: Host on VPS at https://vps.loust.pro:999/netboozt/assets/

  • ❌ playwright/, .playwright/ - Browser automation cache

    • Why: Binary dependencies, platform-specific
    • Type: Tool cache

  • ❌ *.log, *.bak, *backup*.json - Runtime artifacts

    • Why: User-specific, generated during use
    • Type: Temporary data

Committed Alternative for Users:

  • ✅ tools/README.md - Documentation of dev tools
  • ✅ docs/ASSET_HOSTING.md - How to host/access screenshots
  • ✅ PROJECT_SETUP.md - Complete project overview

See: docs/ASSET_HOSTING.md for full guide

📚 Documentation Hierarchy

English (Primary)

README.md                    # Main entry point
├── Quick Start
├── Features
├── Architecture diagrams
└── Links to detailed docs

docs/
├── FAQ.md                   # Troubleshooting, Q&A
├── ASSET_HOSTING.md         # VPS/GitHub strategy
├── optimizations/
│   ├── tcp-congestion-control.md
│   └── bbr-vs-cubic.md      # BBR vs CUBIC comparison ✅
└── diagrams/
    ├── architecture.md      # Mermaid system diagram
    └── optimization-flow.md # Mermaid flowchart

Spanish (Localized)

README.es.md                 # Spanish README ✅
docs/es/                     # Future: full Spanish docs
└── FAQ.es.md               # Future

🔧 Development Tools

Screenshot Generation

File: tools/generate_screenshots.py Purpose: Auto-capture GUI for docs Dependencies: playwright, pillow (gitignored in requirements-dev.txt)

Usage:

pip install playwright pillow
playwright install chromium
python tools/generate_screenshots.py

Output:

  • docs/assets/screenshots/*.png (full size)
  • docs/assets/screenshots/thumbs/*.png (400x300)

Note: Screenshots gitignored, upload to VPS manually

Favicon Generation

File: tools/create_favicon.py Purpose: Generate favicons from LOUST logo Dependencies: pillow

Usage:

python tools/create_favicon.py

Output: All favicon sizes in docs/assets/logo/

🤖 GitHub Configuration

CI/CD Workflows

  • ✅ .github/workflows/ci.yml - Test on Windows/Linux, Python 3.10-3.13
  • ✅ .github/workflows/release.yml - Auto-publish to PyPI on tags

Pre-commit Hooks

  • ✅ .pre-commit-config.yaml - black, isort, flake8, mypy
  • ✅ Enforces code style before commits

Git Initialization

Script: init-git.ps1 Usage:

.\init-git.ps1
# Follow prompts for git config
# Creates initial commit with all files
# Sets up remote: git@github.com:louzt/NetBoozt_InternetUpgrade.git

First push:

git push -u origin main

📊 BBR vs CUBIC Documentation

Key Document: docs/optimizations/bbr-vs-cubic.md

Content:

  • 🔍 Explanation of CUBIC (Windows default)
  • 🚀 Explanation of BBR (Google algorithm)
  • 📈 Performance comparisons (throughput, latency)
  • 🪟 NetBoozt's BBR-like implementation for Windows
  • 🎯 Use cases and recommendations
  • 🔬 Technical deep dive with formulas
  • 🛠️ Configuration instructions

Key Insight: CUBIC detects congestion via packet loss → reactive, high latency BBR detects congestion via RTT increase → proactive, low latency

NetBoozt Strategy: Since Windows can't use BBR directly, we optimize:

  • ✅ HyStart++ (fast slow-start like BBR)
  • ✅ PRR (smoother recovery than CUBIC)
  • ✅ ECN (congestion signals without loss)
  • ✅ TCP Pacing (BBR-like smooth sending)

Result: +15-20% throughput, -12% to -30% latency

🎯 Best Practices Applied

Code Quality

  • ✅ All Python code in English
  • ✅ Google-style docstrings
  • ✅ Type hints for public functions
  • ✅ PEP 8 formatting (black, isort)
  • ✅ Linting (flake8, pylint)

Documentation

  • ✅ Main README in English
  • ✅ Spanish localization (README.es.md)
  • ✅ Comprehensive FAQ
  • ✅ Architecture diagrams (Mermaid)
  • ✅ Per-optimization documentation

Git Hygiene

  • ✅ Semantic commits (feat:, fix:, docs:)
  • ✅ Conventional changelog
  • ✅ .gitignore properly configured
  • ✅ Small assets committed, large assets external

Branding

  • ✅ LOUST logo as app icon (not generic "N")
  • ✅ Consistent favicon across platforms
  • ✅ Professional README with badges
  • ✅ Clear contact email (opensource@loust.pro)

🚀 Next Steps

Before Git Push

  1. ✅ Review all files
  2. ✅ Test favicon generation
  3. ✅ Verify all emails updated
  4. ⏳ Run init-git.ps1
  5. ⏳ Push to GitHub

After GitHub Publish

  1. Setup VPS asset hosting (Nginx config)
  2. Generate screenshots with tools/generate_screenshots.py
  3. Upload screenshots to VPS
  4. Update README with screenshot URLs
  5. Create GitHub Releases with changelog

Future Development (v1.1.0)

  1. Linux module with native BBR
  2. WSL hybrid optimization
  3. Automated testing (pytest)
  4. GitHub Actions running
  5. PyPI package publication

📞 Support & Community

Project Status: ✅ Ready for GitHub Publication
Version: 1.0.0
Last Updated: November 10, 2025
Maintainer: LOUST (www.loust.pro)