Refactoring block #1

[jankapunkt]

Although we should implement refactoring as a constant part of our dev process, we started off with a rather rapid prototyping and left things a bit unmanaged due to the fast paced development cycles. Therefore we should introduce constant refactoring with an initial refactoring sprint.

Estimated effort: 1 week, two devs

Objectives

• clear abstractions and APIs to maximize extensibility
• decent test coverage to detect regressions early and precise
• understandable class/function/variable naming
• detect context boundaries and restructure towards them
• prepare for plugin architecture

Resources

• refactoring book: https://www.oreilly.com/library/view/refactoring-improving-the/9780134757681/
• catalog of refactoring pattern: https://refactoring.com/catalog/
• architecture pattern: https://www.oreilly.com/library/view/software-architecture-patterns/9781491971437/
• clean code: https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/
• domain driven design: https://www.oreilly.com/library/view/domain-driven-design-tackling/0321125215/
• Laravel Documentation: Laravel Latest Documentation
• Clean Code: "Clean Code: A Handbook of Agile Software Craftsmanship" by Robert C. Martin Link
• TODO: add Vue.js (@jankapunkt)

We can access the books via our Uni VPN

Tasks

Note: This is an outline / high level view of the tasks. Each task should be implemented by a pull request. Let's try to avoid big
(and unreviewable) pull requests by implementing multiple tasks in one PR (leading to 50+ files to review 🥵)

Backend @alessandrobelli

To refactor the backend logic efficiently, we follow a structured set of rules. Key points include:

• MVC Paradigm: Models interact with the database, Controllers process data, and Views present the results.

• Separation of Concerns: Each component has a distinct responsibility, improving maintainability.

• DRY Principle: Encourage code reuse and avoid duplication.

• Consistent Naming: Use consistent naming conventions across all components.

• Encapsulation: Encapsulate business logic and validation within models or service classes.

• Review and Refactor Models:

  • Ensure proper use of Eloquent for interacting with the database.
  • Try to use scopes as frequently as possible.
  • Use $fillable, $timestamps, $primaryKey, $auditExclude, $casts and other properties correctly.
  • Implement necessary relationships and encapsulate business logic within models.

• Review and Refactor Controllers:

  • Ensure each controller follows the Single Responsibility Principle as closely as possible.
  • Use proper naming conventions for controllers.
  • Move business logic to service classes where applicable.
  • Implement or refactor to standard methods (index, show, store, update, destroy) when possible.

• Optimize Database Interactions:

  • Implement chunking for processing large datasets.
  • Cache frequently accessed data, if there are any.
  • Analyze and optimize query performance.

• Implement Form Requests:

  • Create Form Request classes for validation and authorization.
  • Refactor existing validation logic out of controllers into Form Requests.

• Review and Improve Policies:

  • Ensure all permissions and policies are correctly defined in app/Policies.
  • Refactor and simplify policy methods for better maintainability.

For an in-depth document on general guidelines about refactoring, check this document: backend refactoring guidelines.

Frontend @jankapunkt

• restructure / rename Files and folders
• Extract common code into reusable components and HOCs
• Make components testable / add unit tests
• extract Visualization plugins into own NPM packages
• Add component documentations
• Add storybook to the project to prepare transition to new design system
• Prepare tailwind classes and components for light/dark theme switching

[alessandrobelli]

I included the part for the backend, and replaced my name with yours for the frontend... that should be it, right? 😄