refactor, linting, formatting, type hints, optimize

[rsgalloway]

it would be good to refactor the code base a bit, do some formatting, cleanup and add type hints.

• code refactoring and cleanup
• linting
• formatting
• type hints
• code optimization
• address TODOs and FIXMEs