[SIP-99] Proposal for correctly handling business logic

[john-bodley]

[SIP-99] Proposal for correctly handling business logic

Whilst spelunking through the code as part of [SIP-92] Proposal for restructuring the Python code base it became apparent* that our grasp of SQLAlchemy sessions, atomic units of work, model/business validation, etc. was likely incorrect or misconstrued—resulting in overly complex or redundant Data Access Objects (DAOs), Commands, event handlers, tests, etc.

* A benefit of refactoring the code into functional units highlighted the various discrepancies which exist.

This SIP serves as an umbrella for a series of lightweight backend SIPs related to defining best practices and guidelines for core/foundational constructs including:

• [SIP-99A] Primer on managing SQLAlchemy sessions
• [SIP-99B] Proposal for (re)defining a “unit of work”
• [SIP-99C] Proposal for model and business validation
• [SIP-99D] Proposal for consolidating Command/DAO create, update, and upsert operations

The hope is (if enacted) that these SIPs should:

• Simplify the code
• Simplify testing
• Simplify the mental model
• Improve the code quality
• Ensure the business layer represents a “unit of work”
• Ensure that the code adheres to the DRY principle
• Improve the developer experience
• Provide clear guidance on the subject and examples of accepted code standards

Proposed Change

Please refer to the related SIPs for details.

New or Changed Public Interfaces

Please refer to the related SIPs for details.

New Dependencies

Please refer to the related SIPs for details.

Migration Plan and Compatibility

Please refer to the related SIPs for details.

Rejected Alternatives

Please refer to the related SIPs for details.

[michael-s-molina]

Thank you for writing this set of SIPs @john-bodley! I look forward to the changes.

[mistercrunch]

Overall the proposals seem very sound and virtuous. Curious on the assessment around how much work the refactor represents (seems fairly massive) and curious about a suggested approach in terms of rolling out the refactor (model-centric?) and whether to start with the most used ones, or the simplest ones (?)

[john-bodley]

Thanks for the comment @mistercrunch. In terms of rollout prioritization, I sense this is somewhat up for debate as like [SIP-92] Proposal for restructuring the Python code base this represents a sizable amount of work.

Part of the SIP is merely defining best practices/patterns (materialized as a wiki page) which can serve as a North Star reference that new code should adhere to. Some facets are likely more piecemeal—like consolidating the create and update logic, validation, etc.—where as others are likely more wholesale—like (re)defining a "unit a work" by leveraging a nested session.

Personally I sense trying to tackle the SIPs in the order they are presented (if possible)—SIP-99B, SIP-99C, and then SIP-99D—likely makes the most sense.

[rusackas]

Approved!

[rusackas]

If anyone here can give an update on implementation status / plans it would be appreciated :D