docs: add codebase visualization guide and documentation improvements

[ryanmccann1024]

Description:
This PR adds comprehensive documentation for visualizing the FUSION codebase architecture and class relationships using pydeps and pyreverse. Additionally includes documentation structure improvements and outdated link fixes.

This branch (refactor/docs) contains 350 commits representing significant refactoring, testing, and documentation work. The most recent commits focus on developer documentation improvements.

🔧 Type of Change

Primary Change Type:

• 📚 Documentation - Documentation only changes (most recent commits)
• 🧪 Tests - Comprehensive test suite additions
• 🔄 Refactor - Code quality and standards compliance
• 🔒 Security - Bandit security fixes
• 🐛 Bug Fix - Non-breaking change that fixes an issue
• ✨ New Feature - Non-breaking change that adds functionality
• 💥 Breaking Change - Change that would cause existing functionality to break
• 🏗️ Build/CI - Changes to build process or CI configuration
• 🎨 Style - Code style changes (formatting, missing semicolons, etc.)
• ⚡ Performance - Performance improvements

Component(s) Affected:

• Documentation (docs/)
• All modules (testing and refactoring)
• Code quality tooling
• CLI Interface (fusion/cli/)
• Configuration System (fusion/configs/)
• Simulation Core (fusion/core/)
• ML/RL Modules (fusion/modules/rl/, fusion/modules/ml/)
• Routing Algorithms (fusion/modules/routing/)
• Spectrum Assignment (fusion/modules/spectrum/)
• SNR Calculations (fusion/modules/snr/)
• Visualization (fusion/visualization/)
• GUI Interface (fusion/gui/)
• Unity/HPC Integration (fusion/unity/)
• Testing Framework (tests/)
• GitHub Workflows (.github/)
• Build/Dependencies

Recent Commits (HEAD)

Most Recent Documentation Commits:

1. de95a65 - chore: ignore generated diagrams in reports/diagrams
2. a12891b - docs: add codebase visualization guide for developers
3. 4682e48 - docs: fix outdated links and references in documentation
4. 2660a39 - docs: refactor documentation structure and build system

Branch Summary (350 total commits):

• Documentation improvements (visualization guide, structure, links)
• Comprehensive unit test suites for all modules (rl, spectrum, snr, ml, utils, unity, sim, reporting, io, interfaces, core, configs, cli)
• Code quality improvements (ruff, mypy, bandit compliance across all modules)
• Refactoring (module cleanup, coding standards, architecture improvements)
• Earlier work (CLI refactoring, config system improvements)

🧪 Testing

Test Coverage:

• Unit tests added/updated (comprehensive test suites across all modules)
• Integration tests added/updated
• Manual testing performed (documentation verified)
• Existing tests still pass
• Performance impact assessed (minimal)

Test Details:
Documentation changes tested by:

• Running pydeps and pyreverse commands as documented
• Verifying generated diagrams display correctly
• Confirming gitignore properly excludes generated files
• Building and reviewing documentation locally

Commands to Reproduce Testing:

# Test visualization tools
pydeps fusion --max-bacon=2 --exclude '**/tests/**' --cluster -o reports/diagrams/arch.png
pyreverse -o png -p rl fusion/modules/rl/

# Verify diagrams are ignored
git status  # Should not show .png files in reports/diagrams/

# Build documentation
cd docs
make html
open _build/html/developer/visualizing_codebase.html

Test Results:

• Operating System: macOS (Darwin 25.0.0)
• Python Version: 3.11
• Test Environment: local development

📊 Impact Analysis

Performance Impact:

• No performance impact (documentation only for recent commits)
• Performance improved
• Minor performance decrease (acceptable)
• Significant performance impact (needs discussion)

Memory Usage:

• No change in memory usage
• Memory usage optimized
• Minor increase in memory usage
• Significant memory impact

Backward Compatibility:

• Fully backward compatible
• Minor breaking changes with migration path
• Major breaking changes (requires version bump)

Dependencies:

• No new dependencies (documentation recommends pylint, pydeps, graphviz for visualization)
• New dependencies added (list in Additional Notes)
• Dependencies removed/updated

🔄 Migration Guide

Breaking Changes (if any):
None - documentation only changes in recent commits.

Migration Steps:
No migration required.

✅ Code Quality Checklist

Architecture & Design:

• Follows established architecture patterns
• Code is modular and follows separation of concerns
• Interfaces are well-defined and documented
• Error handling is comprehensive
• Logging is appropriate and informative

Code Standards:

• Code follows project style guidelines (ruff, mypy, bandit compliance)
• Variable and function names are descriptive
• Code is properly commented
• Complex logic is documented
• No dead code or unused imports

Configuration & CLI:

• CLI arguments follow established patterns
• Configuration validation updated (if needed)
• Schema updated for new config options
• Backward compatibility maintained for configs

Security:

• No sensitive information hardcoded
• Input validation performed where needed
• No security vulnerabilities introduced (bandit fixes applied)
• Dependencies scanned for vulnerabilities

📚 Documentation

Documentation Updates:

• Code comments added/updated
• API documentation updated
• User guide/tutorial updated
• Configuration reference updated
• CHANGELOG.md updated (needs update)
• README updated (if needed)

New Documentation:

• docs/developer/visualizing_codebase.rst - Comprehensive guide for visualizing codebase
  • Installation instructions for pydeps and pyreverse
  • Usage examples and common commands
  • Recommended workflow for planning development
  • Tips, best practices, and troubleshooting
• reports/diagrams/.gitignore - Ignore generated visualization files

Documentation Improvements:

• Fixed outdated links and references throughout documentation
• Refactored documentation structure and build system
• Added visualization guide to developer documentation index

Examples Added:

• Usage examples in docstrings
• Configuration examples (N/A)
• CLI usage examples (pydeps and pyreverse commands)
• Integration examples (workflow for development planning)

🚀 Deployment

Deployment Considerations:

• Safe to deploy to all environments (documentation only)
• Requires environment-specific configuration
• Needs database migration (if applicable)
• Requires manual steps (document below)

Manual Steps Required:
None for documentation changes. Developers can optionally install visualization tools:

pip install pylint pydeps graphviz

🔍 Review Guidelines

For Reviewers:

• PR description is clear and complete
• Code changes align with described functionality
• Tests are comprehensive and pass
• Documentation is adequate
• No obvious security issues
• Performance impact is acceptable

Review Focus Areas:

• Verify visualization guide is clear and accurate
• Test pydeps and pyreverse commands work as documented
• Review documentation structure improvements
• Confirm gitignore properly excludes generated files

📝 Additional Notes

Context:
This PR originates from the refactor/docs branch which has been a long-running effort encompassing:

• Comprehensive unit testing across all modules
• Code quality improvements (ruff, mypy, bandit compliance)
• Module refactoring and coding standards adherence
• Documentation improvements

The most recent commits (listed above) focus specifically on adding developer documentation for codebase visualization tools.

Visualization Tools Added to Documentation:

• pydeps: Shows module architecture and connectivity (how modules import each other)
• pyreverse: Shows class design and relationships (OOP structure, inheritance, associations)

Use Case:
Developers can now easily visualize project structure to:

1. Understand overall architecture before making changes
2. Identify which modules to modify for new features
3. See class relationships and inheritance hierarchies
4. Plan development work more effectively

Open Questions:
None

Future Work:

• Consider automating diagram generation in CI/CD
• Add more example diagrams to documentation
• Integrate with documentation build process

Related PRs:
None

---

🏁 Final Checklist

Before submitting this PR, confirm:

• I have followed the contributing guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works (N/A for docs)
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published