Grouping by feature

[kyranjamie]

Forward: Sorry for the essay. I'm debugging the transaction signing flow and feeling the pain of all the code I need to reference being spread out in various unrelated folders. This topic's come up a few times, so writing my thoughts while they're fresh.

Currently we group by technology in many places. Hooks are grouped by the fact they're hooks. Components are all grouped together unless they're the upper page route etc (regardless of whether they're global or only used for a single feature)

I'd like to put forward a case why this isn't optimal, and why grouping by feature is a much more developer-friendly, thoughtful way to go about organising a scalable codebase.

Starting with components. Consider the extension popup when you create a transaction request. The components that create most of this are in two places:

• src/pages/transaction
• src/components/transactions

Many of the transaction components in src/components are only used in the context of src/pages/transaction.

Similarly with our hooks. We have a src/common/hooks/transaction folder. There are hooks in here only used as part of this transaction flow.

What if, instead, we organise by the features we're building, rather than the what elements of the React toolbox it is we're using to build them?

Here are some reasons against grouping by technology:

• Endless scrolling: I'm working on the tx signing flow right now, and when looking at the directory tree, I have to scroll through loads of unrelated features to get to the right file (even with the minimum required folders being open), because we're breaking up the feature in many places. It's an unnecessary cognitive load lol, and generally makes finding the code you need harder.
• We've learnt this lesson before: If you've ever worked on an app during the MVC days, you've no doubt had a feature split between all 3. This quickly becomes unmanageable. I've seen this style organisation become a huge pain/refactor job, a mistake I don't want to repeat.
  • Technology organisation:
    • src/models/transactions.ts
    • src/controllers/transactions.ts
    • src/views/transactions.ts
  • Feature organisation:
    • src/transactions/transaction.model.ts
    • src/transactions/transaction.controller.ts
    • src/transactions/transaction.views.ts
• Scalability: The term is a cliché but it's true. Do we just keep adding components/hooks to a folder, no matter the size of the app?
• Information loss: The components folder to me is "all components that are shared across the app". Right now we use it as both feature components and shared components. That's helpful information that cannot be inferred by the directory structures.
• Technology doesn't matter: Hooks are a construct of React. We use React. What does a developer gain by seeing all hooks in once place? We never work on all of them at once. We wouldn't organise root level ts/css/html folders. I'd go as far as saying the fact something is a hook/of a given language etc is largely irrelevant. We work on features.

Suggestion
I'd reserve the src/common and src/component folders only for reusable hooks/components/etc across the app. Within the context of a shared folder, they may be organised by technology, or sub-feature, whatever works.

Everything else relates to a feature such as: transaction signing, the settings dropdown, sending an asset flow etc are put into a features folder. If you're not working on tx signing, you can safely ignore everything in that folder. That's a huge win for me. I find myself really unproductive in this repo because there's too much going on. I have to constantly search the entire codebase to figured out "where is x used", which oftentimes I should be able to infer from the directory structure.

src/
  features/
    transaction-signing/
      transaction-signing.page.ts
      transaction-signing.hooks.ts <-- either a single file
      hooks/                       <-- or a folder
      components/                  <-- all components only used in this feature

Personally I'd have a much easier time working with the wallet if we followed a structure like this. Interested to hear your thoughts @aulneau @fbwoolf

[aulneau]

yay our first discussion! I have wanted to use this feature more, so thank you for creating this!

First off, I totally agree, I think there can be a lot of room for improvement and I generally agree with what you're laying out here.

I would be super open to trying out organization by feature, rather than by type or kind of technology/pattern used, with two requests:

I think we should keep store and pages as top level directories in the project. It might be the case that transaction-signing is both a feature and a page, but in my view, pages are typically collections of features and not one feature. Take the home page for example. "Home" is not a feature, but contains main features: send/receive buttons, transaction history, balance listings etc etc.

Additionally, it's very rare that an atom or bit of state is used in only one feature, they are often used between features and referenced in many ways due to the derived nature of our application state. I would hate to have some state here and some state in different folders due to the feature they are semi-related to.

If you are okay with these two requests, I would love to move towards this way of organizing the project!

[fbwoolf]

That all makes sense to me for sure. Where do hooks live at this point?

[fbwoolf]

It seems like hooks should at least be pulled out of common like in the desktop wallet? I feel like they are somewhat buried atm. I have a hard time with just a long list of hooks, I am trying to think about how it might be better to organize them? Would it ever make sense to locate only ones using the store at a level equal to the store, but any just specific to a component or feature located with that component/feature?

[kyranjamie]

Either with their respective feature, or where they are now if shared amongst the rest of the app/global. I agree with you, though. common/hooks are just as "common" as the store is, so don't why they should be on another level.

I'll let you fight that one out with @aulneau though lol

[aulneau]

I am totally fine with hooks being brought out and honestly don't know why they are in common lolol.

However, I am very much against the idea of having any hooks in store. I think if this is what we do:

- common
  - constants.ts
  - utils.ts
- components
  - drawer.tsx
- features
  - accounts-drawer
  - networks-drawer
- pages
  - transaction-signing
    - hooks/use-something-only-found-in-this-page-and-not-in-another-feature.ts
    - components/confirmation-drawer.tsx
- hooks
  - use-something-shared-between-features.ts
- store
  - all state stuff

I can get behind it. I think the hard part will be when we find that things are actually shared more than we realize.

[fbwoolf]

Yes, absolutely! Did not mean to suggest they be in the store. I agree 100% with what you ^ outlined. 💯