Design decisions for the frontend of DocsGPT

[adeyinkaezra123]

To start with, hats off to the maintainers of this repo. Your dedication and hard work have truly made a difference.

Intro

I started working on this repo not so long ago, and I noticed quite a few concerns regarding the design decisions of the frontend side of DocsGPT

I totally understand the ship fast, fail fast strategy, and I resonate deeply with the if it's not broken, don't fix it philosophy, as most developers are mainly concerned with over-optimizations and trying to build with the latest frameworks and stuff, rather than focusing on the core features. But maybe this repo could use some help

I feel like a discussion would be more appropriate as it would open up a new phase of understanding the reasons behind these decisions, and might serve as a source of truth for newer decisions to be made

I recently began my involvement with this repository, and I've observed certain concerns related to the front-end design choices in DocsGPT. I fully understand the "ship fast, fail fast" approach and resonate with the "if it's not broken, don't fix it" philosophy, as any developers tend to prioritize excessive optimizations and adopting the latest frameworks over core features.
However, I believe that this repository could benefit from some improvements.

In my view, initiating a discussion, rather than raising multiple PRs would be more appropriate. It could pave the way for a deeper understanding of the rationale behind these decisions and establish a foundation for making future decisions based on a shared understanding.

Suggestions

Embracing the Single-responsibility principle

A function — and therefore a React component — should be doing one thing. Typically, it is best practice to create React components in their own files and export them for use in other files that need them as allows you to reuse and share components and makes it easier to manage complex logic.

• All components should be pure functions with respect to their props
• All functions that have a requirement for state or other component lifecycle functionality, should be moved into its own file or at least outside of the current component.
• Reusable components go into their own files, whereas components that are dependent on each other for a specific purpose go into the same file

Moving to a structured Development environment for UI components

Since developers with various engineering backgrounds and software development preferences may contribute to this repository, it's crucial to establish well-organized UI systems. This will enhance efficiency in both the development process and documentation. Utilizing a UI development environment like Storybook ensures that UI components adhere to strict guidelines based on validated design decisions, rather than relying solely on visual interpretation from a Figma design.

Tests, was surprised none exists yet

The title is quite clear. Nevertheless, a successful test must guarantee how the application (or a specific component) behaves from a user's viewpoint. Writing tests to validate implementation specifics is a misuse of precious time, and the test coverage would offer only a deceptive sense of security.

Moving to a monrepo

This is opinionated, as not all teams can tap into monorepo benefits:

• Consistency thanks to atomic commits — all project builds will work at any commit.
• Code reusability — identify standard components and share common functionality across monorepo microservices

[dartpain]

Hi @adeyinkaezra123 ,

Thank you for your input.
I think you brought up very important notes and I agree with you here.

We recently introduced tests for backend and forntend needs them too. and our UI review process is suffering
We also recently had a large backend restructre to make code extensible for the future and FE deserves this too.

1. We do need to restructure code to take full benefit of components. I think we need to create and issue and change contributing,md to reflect it. If you can help in this process I would appreciate it a lot!
2. Lets add storybook once we make some progress on 1.
3. Should we use https://jestjs.io/ for this, any recommendation?
4. I think we will delay this for a bit, but definetly something we need to do. As we will add more UI plugins/extension

[adeyinkaezra123]

1. I'll address some concerns regarding that, and if there's time, I'll tackle a few of them.
2. Sounds good, let's start with number 1 and go from there.
3. Given that this project is already based on Vite, I recommend using Vitest as it's designed to be a faster alternative to Jest for unit tests, utilizes Playwright for component testing in end-to-end scenarios, and Storybook also incorporates a test runner that utilizes Playwright under the hood.
4. Certainly, that's why I mentioned it's somewhat opinionated. However, the initial step of co-location is completed, so the migration should be smoother.

[dartpain]

Thank you! Appreciate it.

3. Yep lets go with vitest, since project is already using vite.