Define overall architecture for kaiaulu react and necessary libraries

[austindang67]

Look into "bulletproof-react" as a basis for our project structure. Start looking into unit testing libraries. Create a vite-react project.

https://github.com/alan2207/bulletproof-react

https://react.dev/learn/thinking-in-react

https://martinfowler.com/articles/modularizing-react-apps.html

Bulletproof-react will create a basis for maintainability that can be expanded upon by future collaborators on this project. It is proven and scalable, and as a result will make it easier for future developers to be on-boarded. Refactoring will be easier as well.

As for unit-testing, Vitest will be our choice as it is Vite-native and our project is Vite + React. It runs fast and tests real app behavior.

Network Graph Data Architecture

Hooks

• useGraphData
• useJsonFiles
• useGraphLayout
• useGraphInteractions
• useGraphNodeResizing (will further discuss)

[carlosparadis]

@austindang67 Please see the CONTRIBUTIONS.md on how to format your commit messages to tie to an issue id. Your first commit violates the rule.

Further, please initialize the repo with just a README.md and add the main code as a PR so I can review the structure. As it stands, I am unable to comment as it is directly on main branch. For both commits, use this issue ID as a reference.

Lastly, the issue has to reflect the memory of the task. Please include the resources I shared with you here and expand on the goal. Your first issue should reflect the vision of the project we discussed and its intended architecture. As a comment reply, please expand how you would reuse bullet proof react and the other links to organize the code so we can start seeing if we are on the same page.

Thanks!

[austindang67]

I plan on using bullet proof react as a basis for structuring the front-end. I will emphasize organizing code by "features" while keeping generic code in a shared area. The layers will be clear, separated by features, utilities, components, and more.

I am familiar with approaching react from a "as modular as possible" standpoint as the company I am interning with maintains these standards. Code is to be made as scalable and maintainable as possible because of how much a project can grow. A project built on faulty foundations is harder to build upon. Splitting view and non-view code into different places is a standard I am familiar with. I am also familiar with state management via hooks.

[carlosparadis]

@austindang67 It is my current understanding you have not implemented any guidelines of bullet proof, is that correct?

[austindang67]

@austindang67 It is my current understanding you have not implemented any guidelines of bullet proof, is that correct?

@carlosparadis Hi Carlos, I have been implementing some guidelines of bullet proof react, such as separation of data from logic, keeping style close to components, and trying to use primitive components where I can. I am currently working on refactoring to better match the guidelines. Apologies for the confusion, I went down the rabbit hole of getting D3.js to work.

[carlosparadis]

Thank you for the update. The main things to keep in mind are the separation of components and hooks. etc per feature, and that also gets moved to a separate folder. It also concerns the assignment of responsibility of what code does what and where. I suggest you discuss the folder architecture here before going through. E.g., you could make a copy of your folder with the code, move files around, take a screenshot, and post here, for example.

It is OK, you try to get things to work first, but I advise against going too far without thinking through the code architecture or we risk all effort not being able to be extended in subsequent sessions due to maintenance cost or learning curve being too steep (it has to fit a class session after all!).

[austindang67]

@carlosparadis

Hey Carlos, here is the commit in which I separated the node data into separate JSONs according to their type (Person, Mail, Issue, File): 03e0324

Here is the meeting summary for 11/6/25:
#3 (comment)

Let me know if you have any questions.

[carlosparadis]

I moved your comment above to #6 to avoid confusion.

The purpose of this issue is different and directly tied to your cheatsheet. This has more to do with the way you are organizing the abstractions of the code and its final form using bulletproofreact (see: #5 (review)).

As discussed on call, Kaiaulu react will not have a backend on its incarnation. However, it builds on top of Kaiaulu architecture to offer real-time data if the user so wishes.

Let's consider Kaiaulu React architecture first in respect to its features. We have as features:

1. Display people, file, mail and issue abstractions in a single graph.
2. Gravity layout for the four types of data, with people on center.
3. A consistent color scheme to what Kaiaulu R uses.
4. The ability to select a node to see an overlay.
5. The ability to double click a node to see the subgraph of it highlighted
6. The ability to search people/file/mail/issue by a few fields which highlight only nodes and fades everything else, including edge. This feature interacts with 4 to facilitate identifying interaction 5 without requiring tedious searching every attempt.
7. The ability to specify in the data that is loaded, information that defines the weight and label of nodes and edges, which affect the size and display of information.
8. (Missing but ideal): The ability to enable display text after a certain zoom level, like Kaiaulu does
9. The ability to read a configuration yml file that sits inside the client folder that contains the filepath to the data objects for file, people, mail and issue (those of which are .json and produced by Kaiaulu execs).

What I would have liked to see in this issue is how you plan to turn all of the above into code. What files, what components, what hooks. Insofar, everything seems to be colased inside a god class (function?) NetworkGraph. The intent of creating this issue on Day 1 was to avoid a single that would now require splitting the code out.

Please let me know how you plan to proceed on this.

[austindang67]

@carlosparadis Hey Carlos, I have updated the first comment with a rough diagram of the Network Graph architecture, let me know if you have any questions or suggestions.

[carlosparadis]

• I do not see reflected here the different types of graphs I defined in the other issue. I would expect you need useGraphMailData, useGraphIssueData, etc, no? These in turn would be obtained through the project configuration file. Would not need a useProjectConfiguration file to read its content somewhere? Note the useGraph functions should presume the general node and link types instead of the specialized ones so you do not associate them to every type of graph.

• While I am familiar with the abstraction of components on React, I am less so with "Context". Could you elaborate?

• Please rename useSimulation to useGraphLayout. That is the nomenclature also used in Gephi. Rename useInteractions to useUserGraphInteraction.

• I am not seeing hooks responsible for the resize of nodes and links, or the display of label. Should that not be set explicitly elsewhere?

• Suppose a new layout algorithm to display the graph in the future will be added. What would need to modify in your code? We want to enable a function that does most of the work, but is extensible to different layouts. The same is true for different behavior affecting the nodes and links (e.g. if we want to add behavior to change color, what would need to change in your code?). What if we want to add a new type of graph to be read? How would that look like? What parts of the code would I need to change? If the answer to any of these requires modifying the code everywhere, then the architecture is not modular enough. Lastly, suppose I want to add a new interaction, what would need to be modified? I believe you still have overloaded god classes going on here. One to handle all interactions, one to handle all data loading, etc. This in Kaiaulu would be equivalent of a R/downloader.R which would pile up download from all data sources, as opposed to R/jira.R, R/github.R, etc.

Lastly, what logic is currently on utils?

Note, I am reasoning this through an architecture standpoint, not a typescript developer. Please give some thought to the merits and demerits of the above so we can iterate here.

Thank you for the diagram! Please give the above some thought and share a new one so we can discuss it before the meeting. The more passes are asynchronous, the sooner we can converge.