Epic: Next Feature Development - Build System and Documentation Improvements

.gitignore

@@ -9,6 +9,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 build/
+builds/
 develop-eggs/
 dist/
 downloads/

build_local.bat

@@ -0,0 +1,273 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo ===============================================
+echo PyFlowGraph Local Build Script
+echo ===============================================
+echo.
+
+REM Check if we're in the correct directory
+if not exist "src\main.py" (
+    echo ERROR: main.py not found in src directory
+    echo Please run this script from the PyFlowGraph root directory
+    pause
+    exit /b 1
+)
+
+if not exist "requirements.txt" (
+    echo ERROR: requirements.txt not found
+    echo Please run this script from the PyFlowGraph root directory
+    pause
+    exit /b 1
+)
+
+echo [1/6] Checking prerequisites...
+
+REM Check if Python is installed
+python --version >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: Python is not installed or not in PATH
+    echo Please install Python 3.11 or later
+    pause
+    exit /b 1
+)
+
+REM Check if zstd is available (needed for runtime download)
+zstd --version >nul 2>&1
+if errorlevel 1 (
+    echo WARNING: zstd not found. You may need to install it for Python runtime download.
+    echo You can install it with: choco install zstandard
+    echo Or download manually from: https://facebook.github.io/zstd/
+    echo Continuing without zstd - will try PowerShell for decompression...
+)
+
+echo [2/6] Installing/updating dependencies...
+pip install -r requirements.txt
+if errorlevel 1 (
+    echo ERROR: Failed to install dependencies
+    pause
+    exit /b 1
+)
+
+echo [3/6] Preparing Portable Python Runtime...
+
+REM Check if python_runtime already exists
+if exist "python_runtime" (
+    echo Python runtime already exists, skipping download...
+    goto :build_app
+)
+
+echo Downloading Python runtime (this may take a while)...
+set "PYTHON_URL=https://github.com/astral-sh/python-build-standalone/releases/download/20250808/cpython-3.11.13+20250808-x86_64-pc-windows-msvc-pgo-full.tar.zst"
+
+REM Download using PowerShell with better error handling
+powershell -Command "try { Write-Host 'Downloading Python runtime...'; Invoke-WebRequest -Uri '%PYTHON_URL%' -OutFile 'python-standalone.tar.zst' -UseBasicParsing; Write-Host 'Download completed.' } catch { Write-Host 'ERROR: Failed to download Python runtime'; Write-Host $_.Exception.Message; exit 1 }"
+if errorlevel 1 goto :error
+
+REM Verify download was successful
+if not exist "python-standalone.tar.zst" (
+    echo ERROR: Download failed - python-standalone.tar.zst not found
+    goto :error
+)
+
+echo Decompressing Python runtime...
+zstd -d python-standalone.tar.zst -o python-standalone.tar >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: Failed to decompress runtime with zstd
+    echo Please install zstd using one of these methods:
+    echo   choco install zstandard
+    echo   winget install Facebook.zstd
+    echo   scoop install zstd
+    echo Or download from: https://facebook.github.io/zstd/
+    goto :error
+)
+
+REM Verify decompression was successful
+if not exist "python-standalone.tar" (
+    echo ERROR: Decompression failed - python-standalone.tar not found
+    goto :error
+)
+
+echo Extracting Python runtime...
+tar -xf python-standalone.tar
+if errorlevel 1 (
+    echo ERROR: Failed to extract tar file
+    goto :error
+)
+
+REM Verify extraction was successful
+if not exist "python\install" (
+    echo ERROR: Extraction failed - python\install directory not found
+    goto :error
+)
+
+echo Moving Python runtime to final location...
+if not exist "python_runtime" mkdir python_runtime
+echo Copying Python runtime files with all subdirectories...
+robocopy "python\install" "python_runtime" /E /NP /NFL /NDL
+if errorlevel 8 (
+    echo ERROR: Failed to copy Python runtime files
+    goto :error
+)
+
+REM Verify critical directories exist
+if not exist "python_runtime\Lib" (
+    echo ERROR: Python runtime missing Lib directory - extraction incomplete
+    echo Contents of python_runtime:
+    dir "python_runtime" /B
+    goto :error
+)
+
+REM Clean up temporary files
+if exist "python" rmdir /s /q "python" >nul 2>&1
+if exist "python-standalone.tar.zst" del "python-standalone.tar.zst" >nul 2>&1
+if exist "python-standalone.tar" del "python-standalone.tar" >nul 2>&1
+
+echo Python runtime prepared successfully.
+
+:build_app
+echo [4/6] Building application with Nuitka...
+
+REM Create builds directory if it doesn't exist
+if not exist "builds" mkdir builds
+
+REM Clean previous build
+if exist "builds\NodeEditor_Build" (
+    echo Cleaning previous build...
+    rmdir /s /q "builds\NodeEditor_Build"
+    if exist "builds\NodeEditor_Build" (
+        echo ERROR: Could not remove previous build directory
+        goto :error
+    )
+)
+
+echo Running Nuitka build (this will take several minutes)...
+if not exist "src" (
+    echo ERROR: src directory not found
+    goto :error
+)
+
+cd src
+python -m nuitka ^
+  --standalone ^
+  --enable-plugin=pyside6 ^
+  --include-qt-plugins=platforms ^
+  --output-dir=../builds/NodeEditor_Build ^
+  --output-filename=PyFlowGraph.exe ^
+  --nofollow-import-to=tkinter,unittest,setuptools,pip,wheel ^
+  --windows-console-mode=disable ^
+  --remove-output ^
+  --lto=yes ^
+  --include-data-dir=../examples=examples ^
+  --include-data-dir=resources=resources ^
+  --include-data-file=../dark_theme.qss=dark_theme.qss ^
+  --assume-yes-for-downloads ^
+  main.py
+
+set NUITKA_RESULT=%ERRORLEVEL%
+cd ..
+
+if %NUITKA_RESULT% neq 0 (
+    echo ERROR: Nuitka build failed with exit code %NUITKA_RESULT%
+    goto :error
+)
+
+echo [5/6] Copying Python runtime to build...
+
+set "DIST_DIR=builds\NodeEditor_Build\main.dist"
+
+if not exist "%DIST_DIR%" (
+    echo ERROR: Expected Nuitka output directory not found: %DIST_DIR%
+    echo Available directories in builds\NodeEditor_Build:
+    if exist "builds\NodeEditor_Build" dir "builds\NodeEditor_Build" /B
+    goto :error
+)
+
+if not exist "%DIST_DIR%\PyFlowGraph.exe" (
+    echo ERROR: PyFlowGraph.exe not found in build output
+    echo Contents of %DIST_DIR%:
+    dir "%DIST_DIR%" /B
+    goto :error
+)
+
+echo Copying python_runtime to build directory...
+if not exist "python_runtime" (
+    echo ERROR: python_runtime directory not found
+    goto :error
+)
+
+robocopy "python_runtime" "%DIST_DIR%\python_runtime" /E /NP /NFL /NDL >nul 2>&1
+if errorlevel 8 (
+    echo ERROR: Failed to copy Python runtime to build directory
+    goto :error
+)
+
+echo [6/6] Finalizing build...
+
+REM Get current timestamp for version using PowerShell with error handling
+for /f "tokens=*" %%i in ('powershell -Command "try { Get-Date -Format 'yyyyMMdd-HHmmss' } catch { 'unknown' }"') do set "timestamp=%%i"
+
+if "%timestamp%"=="unknown" (
+    echo WARNING: Could not get timestamp, using default name
+    set "timestamp=build"
+)
+
+echo Organizing build in builds directory...
+
+set "FINAL_DIR=builds\PyFlowGraph-Windows-local-%timestamp%"
+
+REM Remove existing final directory if it exists
+if exist "%FINAL_DIR%" (
+    echo Removing existing build: %FINAL_DIR%
+    rmdir /s /q "%FINAL_DIR%"
+)
+
+REM Move the build directory to final location
+move "%DIST_DIR%" "%FINAL_DIR%" >nul 2>&1
+if errorlevel 1 (
+    echo ERROR: Failed to rename build directory
+    echo Source: %DIST_DIR%
+    echo Target: %FINAL_DIR%
+    goto :error
+)
+
+REM Verify the final executable exists
+if not exist "%FINAL_DIR%\PyFlowGraph.exe" (
+    echo ERROR: PyFlowGraph.exe not found in final build directory
+    goto :error
+)
+
+echo.
+echo ===============================================
+echo BUILD COMPLETED SUCCESSFULLY!
+echo ===============================================
+echo.
+echo All builds are organized in the 'builds' folder
+echo Build location: %FINAL_DIR%
+echo Executable: %FINAL_DIR%\PyFlowGraph.exe
+echo.
+echo Contents of build directory:
+dir "%FINAL_DIR%" /B
+echo.
+
+REM Build completed - showing final information
+echo To run PyFlowGraph: %FINAL_DIR%\PyFlowGraph.exe
+
+echo Build complete.
+exit /b 0
+
+:error
+echo.
+echo ===============================================
+echo BUILD FAILED!
+echo ===============================================
+echo Please check the error messages above and try again.
+echo.
+echo Common solutions:
+echo - Install zstd: choco install zstandard
+echo - Install Python 3.11+
+echo - Install Visual Studio Build Tools
+echo - Check internet connection for downloads
+echo.
+pause
+exit /b 1

docs/README.md

@@ -1,50 +1,80 @@
 # PyFlowGraph Documentation
 
-This directory contains comprehensive documentation for the PyFlowGraph project, organized by purpose and audience.
+This directory contains comprehensive documentation for the PyFlowGraph project, organized following BMAD-inspired structure with clear separation between user documentation, developer resources, and technical references.
 
 ## Quick Navigation
 
-### For Product Strategy & Planning
-- **[PRD](prd.md)** - Product Requirements Document
-- **[Roadmap](roadmap.md)** - Feature development roadmap and priorities
-- **[Competitive Analysis](competitive-analysis.md)** - Missing features vs competitors
+### For Users
+- **[User Guide](user_guide/)** - Getting started, tutorials, and examples
+  - [Getting Started](user_guide/getting_started.md) - Installation and first workflow
+  - [Tutorials](user_guide/tutorials/) - Step-by-step guides
+  - [Examples](user_guide/examples/) - Sample workflows and use cases
 
-### For Architecture & Technical Design
-- **[Technical Architecture](architecture/technical_architecture.md)** - Core system architecture
-- **[Brownfield Architecture](architecture/brownfield-architecture.md)** - Legacy system considerations
-- **[Source Tree](architecture/source-tree.md)** - Codebase organization
-- **[Tech Stack](architecture/tech-stack.md)** - Technology choices and rationale
-- **[Coding Standards](architecture/coding-standards.md)** - Development guidelines
+### For Developers
+- **[Developer Guide](developer_guide/)** - Development environment and contribution guidelines
+  - [Testing Guide](developer_guide/testing-guide.md) - Test runner and testing strategies
+  - [Implementation Notes](developer_guide/implementation-notes.md) - Technical priorities
+  - [AI Agents Guide](developer_guide/ai-agents-guide.md) - Working with AI assistants
 
-### For Feature Specifications
-- **[Flow Specification](specifications/flow_spec.md)** - Core flow format specification
-- **[UI/UX Specifications](specifications/ui-ux-specifications.md)** - Interface design specs
-- **[Priority 1 Features](specifications/priority-1-features-project-brief.md)** - Critical feature brief
+### For Technical Reference
+- **[Reference](reference/)** - Complete technical documentation
+  - [Architecture](reference/architecture/) - System design and technical architecture
+  - [Specifications](reference/specifications/) - Feature and interface specifications
+  - [API](reference/api/) - API documentation (planned)
 
-### For Development & Implementation
-- **[Testing Guide](development/testing-guide.md)** - Test runner and testing strategies
-- **[Implementation Notes](development/implementation-notes.md)** - Technical implementation priorities
-- **[Fixes Directory](development/fixes/)** - Specific implementation and fix plans
+### For Project Management
+- **[Project](project/)** - Strategic planning and development tracking
+  - [PRD](project/prd.md) - Product Requirements Document
+  - [Roadmap](project/roadmap.md) - Feature development roadmap
+  - [Epics](project/epics/) - Epic and story tracking
 
-## Document Organization
+### For Issue Tracking
+- **[Issues](issues/)** - Bug reports and issue resolution
+  - [Active Issues](issues/active/) - Current unresolved issues
+  - [Resolved Issues](issues/resolved/) - Completed issue resolutions
 
-### Strategic Documents
-High-level product and business documentation for stakeholders and product planning.
+### For Implementation Details
+- **[Implementation](implementation/)** - Detailed implementation plans and fixes
+  - [Fixes](implementation/fixes/) - Specific fix implementations
+  - [Migration Plans](implementation/migration_plans/) - Code reorganization plans
 
-### Architecture Documents
-Technical architecture, system design, and structural documentation for architects and senior developers.
+## Document Organization Philosophy
 
-### Specifications
-Detailed feature and interface specifications for development teams.
+This documentation structure follows industry best practices with clear separation of concerns:
 
-### Development Documentation
-Implementation guides, testing procedures, and development tooling for active contributors.
+### User-Focused Documentation (`user_guide/`)
+Practical guides for end users, including tutorials, examples, and getting started materials.
+
+### Developer Documentation (`developer_guide/`)
+Technical development information for contributors, including testing, setup, and implementation guidance.
+
+### Reference Material (`reference/`)
+Comprehensive technical specifications, architecture documentation, and API references for detailed technical understanding.
+
+### Project Management (`project/`)
+Strategic documents, planning materials, and development tracking for stakeholders and project coordination.
+
+### Issue Management (`issues/`)
+Structured bug tracking and issue resolution with proper categorization and documentation.
+
+### Implementation Details (`implementation/`)
+Specific implementation plans, migration strategies, and detailed technical solutions.
 
 ## Contributing to Documentation
 
 When adding new documentation:
-- Place strategic docs in the root `docs/` directory
-- Place technical architecture in `architecture/`
-- Place feature specs in `specifications/`
-- Place implementation details in `development/`
-- Update this README with new document links
+- Place user-focused content in `user_guide/`
+- Place developer information in `developer_guide/`
+- Place technical specifications in `reference/`
+- Place strategic content in `project/`
+- Place bug reports in `issues/`
+- Place implementation details in `implementation/`
+- Always update relevant README files with new document links
+- Follow existing naming conventions and organization patterns
+
+## Navigation Tips
+
+- Each major section has its own README with detailed navigation
+- Related documents are cross-referenced for easy discovery  
+- Status information is maintained for active development items
+- Historical documents are preserved in appropriate subdirectories