[docs] adding more internal notes about the APIs and how things work

[heckj]

Description

Internal notes and a few documentation updates about the current implementation and what I've learned from using it so far.

Motivation and Context

Details for "future me" when I circle back to this after a potential break, so I can remember what the hell I was thinking and the context around it all.

How has this been tested?

n/a

Checklist

• I have updated the documentation accordingly.
• All new and existing tests passed.
• I have run ./scripts/preflight.bash and it passed without errors.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 69.14%. Comparing base (0fe32a6) to head (73b7895).
Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #88   +/-   ##
=======================================
  Coverage   69.14%   69.14%           
=======================================
  Files          26       26           
  Lines        1332     1332           
=======================================
  Hits          921      921           
  Misses        411      411           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.