From c9549c3833e6caeff2032748add764cdb72893c9 Mon Sep 17 00:00:00 2001
From: Weiko <corentin@twenty.com>
Date: Tue, 15 Aug 2023 15:15:07 -0700
Subject: [PATCH] [docs] add folder architecture doc (#1221)

* [docs] add folder architecture doc

* update

* add internal

* improve doc
---
 docs/docs/developer/frontend/_category_.json  |   7 ++
 .../frontend/folder-architecture.mdx          | 116 ++++++++++++++++++
 docs/src/theme/DocSidebarItem/Link/index.js   |   2 +
 3 files changed, 125 insertions(+)
 create mode 100644 docs/docs/developer/frontend/_category_.json
 create mode 100644 docs/docs/developer/frontend/folder-architecture.mdx

diff --git a/docs/docs/developer/frontend/_category_.json b/docs/docs/developer/frontend/_category_.json
new file mode 100644
index 000000000..7ec594c80
--- /dev/null
+++ b/docs/docs/developer/frontend/_category_.json
@@ -0,0 +1,7 @@
+{
+  "label": "Frontend",
+  "position": 3,
+  "collapsible": false,
+  "collapsed": false,
+  "className": "navbar-sub-menu"
+}
\ No newline at end of file
diff --git a/docs/docs/developer/frontend/folder-architecture.mdx b/docs/docs/developer/frontend/folder-architecture.mdx
new file mode 100644
index 000000000..a78143fe8
--- /dev/null
+++ b/docs/docs/developer/frontend/folder-architecture.mdx
@@ -0,0 +1,116 @@
+---
+sidebar_position: 0
+sidebar_custom_props:
+  icon: TbFolder
+---
+
+# Folder Architecture
+
+In this guide, you will explore the details of the project directory structure and how it contributes to the organization and maintainability of Twenty.
+
+By following this folder architecture convention, it is easier to find the files related to specific features and ensure that the application is scalable and maintainable.
+
+```
+front
+└───modules
+│   └───module1
+│   │   └───submodule1
+│   └───module2
+│   └───ui
+│   │   └───buttons
+└───pages
+└───...
+```
+
+## Pages
+
+Contains the top-level components that are defined by the application routes. They import more low-level components from the modules folder (more details below).
+
+## Modules
+
+Each module represents a feature or a group of feature, comprising its specific components, states, and operational logic.
+They should all follow the structure below. You can nest modules within modules; We often refer to them as submodules but the same rules apply.
+
+```
+module1
+  └───components
+  │   └───component1
+  │   └───component2
+  └───constants
+  └───contexts
+  └───graphql
+  │   └───fragments
+  │   └───queries
+  │   └───mutations
+  └───hooks
+  │   └───internal
+  └───states
+  │   └───recoil-scope-contexts
+  │   └───selectors
+  └───types
+  └───utils
+```
+
+### Contexts
+
+A context is a way to pass data through the component tree without having to pass props down manually at every level.
+
+See [React Context](https://react.dev/reference/react#context-hooks) for more details
+
+### States
+
+Contains the state management logic. We use [RecoilJS](https://recoiljs.org) for this.
+
+- Selectors
+
+  See [RecoilJS Selectors](https://recoiljs.org/docs/basic-tutorial/selectors) for more details.
+
+- Recoil Scope Contexts
+
+  More details will be added soon.
+
+We still use React's built-in state management for state that is only used within a component.
+
+### Hooks
+
+See [Hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) for more details.
+
+### Utils
+
+Should only contain reusable pure functions. Otherwise, create custom hooks in the `hooks` folder.
+
+### GraphQL
+
+Includes fragments, queries, and mutations.
+
+See [GraphQL](https://graphql.org/learn/) for more details.
+
+- Fragments
+
+  A fragment is a reusable piece of a query, which can be used in multiple places. By using fragments, it is easier to avoid duplicating code.
+
+  See [GraphQL Fragments](https://graphql.org/learn/queries/#fragments) for more details.
+
+- Queries
+
+  See [GraphQL Queries](https://graphql.org/learn/queries/) for more details.
+
+- Mutations
+
+  See [GraphQL Mutations](https://graphql.org/learn/queries/#mutations) for more details.
+
+## UI
+
+Contains all of the reusable UI components used in the application.
+
+This folder can contain subfolders for specific types of components, such as `buttons`, `inputs`, or `modals`. Each component should be self-contained and reusable, so that it can be used in multiple parts of the application.
+
+By separating the UI components from the other components in the `modules` folder, it is easier to maintain a consistent design and to make changes to the UI without affecting other parts (business logic) of the codebase.
+
+## Interface and dependencies
+
+You can import other module code from any module except for the `ui` folder. This will keep its code easy to test.
+
+### Internal
+
+Each part (hooks, states, ...) of a module can have an `internal` folder, which contains parts that are only used within the module.
diff --git a/docs/src/theme/DocSidebarItem/Link/index.js b/docs/src/theme/DocSidebarItem/Link/index.js
index 4b5595c77..f8a7e2c98 100644
--- a/docs/src/theme/DocSidebarItem/Link/index.js
+++ b/docs/src/theme/DocSidebarItem/Link/index.js
@@ -22,6 +22,7 @@ import {
   TbBrandWindows,
   TbBugOff,
   TbBrandVscode,
+  TbFolder,
 } from "react-icons/tb";
 
 
@@ -51,6 +52,7 @@ export default function DocSidebarItemLink({
     'TbBugOff': TbBugOff,
     'TbBrandVscode': TbBrandVscode,
     'TbDeviceDesktop': TbDeviceDesktop,
+    'TbFolder': TbFolder,
   };
 
   let IconComponent = customProps && customProps.icon ? icons[customProps.icon] : TbFaceIdError;