The aim of the refactoring of NearBeach is to achieve multiple goals. We want to not only remove all tech dept that we have procurred over the years, but also implement best practices and new methods of coding that we have learned. Other items would be to open up the system to plugins and expansions, so custom workflows, AI agents, etc can be implemented into the NearBeach Flow.
We have gotten comments like "If NearBeach had OAuth I would write an app to use it for 'this' particular purpose." and "Can you open up more of NearBeach's API, as I want to automate a few of 'these' tasks" etc. We knew at the time we could not do this due to a large amount of decisions that in hinesight were incorrect and have caused many issues within the development process.
One of those incorrect decisions (made at the start of NearBeach's development), was to include the table name in the field names, and also not to have consistent naming convention through out all of the tables. This made permissions extremely hard to implement and very bug prone.
We have decided to focus on a vertical slice of NearBeach - the projects module. This gives us the ability to quickly setup how we want to code NearBeach, and pivot if our decision was not the best solution. We can setup rules around how the front-end will work with the API to fetch/patch/delete data, and get quicker feedback on everyone's opinion how the new Version 1 API will work.
Once we feel we have achieved all CRUD operations for the front-end, we will be focusing on documentation and testing at the same time. These two goals have had to be put on the back burner due to the every changing and pivoting decisions we have been making. Every time we have made a decision to change how the interactivity works with NearBeach, the unit tests have to also be updated to reflect this change.
From past experience, every single time we implement more unit tests, we find more bugs and issues. We are hoping with the new design decisions we have implemented it will be a quicker and faster turn around.
For the API, we are implementing a Controller -> Service layer. All endpoints for the controller will be thin. They implement/call a service and then send back data. All business logic is inside the service and not the controller.
This gives us the ability - in the future - if we need to implement a different business logic due to a newer API, we can still support the older services until we are happy everyone has moved off them. In which we can then deprecate them.
The code block above can be reached via /api/v1/project/<ID>/organisation/ as is designed to get the following information for the given project;
Organisation information assigned to the current project
Customers assigned to the current project
Potential Organisations that the user can switch too (current functionality might be deprecated as we implement a select with search functionality)
Potential Customers that the user can use to add to project (current functionality might be deprecated as we implement a select with search functionality)
The flow of the code is really simple;
Create the OrganisationService object
Fetch data from the organisation service object
Return data (or notify the user something went wrong)
A side effect of this new coding method we have chosen, is that we now have a lot smaller files. Though we will have a lot more specific files now, that do a specific thing.
As all controller methods are thin, the code becomes more boiler plate. This now gives us the ability to include only the nodes we want for that object. If we don't want to have "Organisations" for the requirements object, we won't include that code within the requirement controller.
Before we had many checks to make sure the user was passing through the correct destination. This is no longer needed as a simple server error will automatically appear;
404 - path not found
405 - method not allowed
A lot - simple put.
One of the goals we want to achieve during this refactor is to move away from Bootstrap, and to create our own dumb component library that we have 100% control over.
The idea behind whelk ui is - dumb components. And when we say dump components we really mean fully dumb components. There will be little to no business logic, and most of the content for each component will still be rendered by the user, using VueJS's <slot /> system.
Whelk Ui will not only be used by NearBeach, but another project that we will discuss later
We are currently only focusing on the projects module. We currently only need to implement the following;
Adding/Removing customers from projects
Adding/Removing/Editing notes from projects
Adding/Removing/Editing public links
Adding/Removing/Editing sprint links
Deleting projects (administration only)
Implementing error handling for the front-end so users are notified if there has been an issue
This list will increase, as there is definitely something missing.
We want to extend our unit tests. We want to have high confidence that every release from NearBeach and Whelk UI. We will be investigating if AI could help us construct some of these tests.
Though AI is not perfect, we are hoping it can spit out more generic/boiler plate tests that we can use. As NearBeach matures we will always be adding in more human written tests for edge cases or business logic the AI has missed. We will be using AI as a tool, not a crutch here.
This will be the longest stage by far. It will require us to analise our code and make it consistent. Everything similar does something similar. Aka no random methods on how to fetch data.
We will also be ruthless toward our UI/UX. Cleaning up layout and how the UI/UX will notify users what is currently happening. i.e. User change the start date of a project -> frontend will need to notify the user when that value has been updated successfully in the backend.
Great news is - we can copy any services/controllers and apply any changes like find and replace. We are hoping once the project module is finished, the tasks module will only take 1 hour to complete and get setup. As the task module essentially works the same as the project module.
Other different modules within NearBeach will need some tweaking, for example requirement module does not contain the ability to assign organisations or customers. However most services should be setup, and ready to use for that module.
We are expecting the other module's development will be a lot quicker.