docs(React): React README (datahub-project#2103)

* Adding React Documentation

* Add image registry

Co-authored-by: John Joyce <[email protected]>

datahub-web-react/README.md

@@ -1,3 +1,124 @@
-This module contains an incubating React App. Please note that this is *not* production-ready and is still in beta. Our initial milestone is to achieve functional parity with the Ember web client. 
+DataHub React App (Incubating)
+==============================================================================
 
-Feel free to explore & contribute! 
+## About
+This module contains a React version of the DataHub UI, which is currently under incubation. Notice that this
+is a completely separate frontend experience from Ember and will remain so as it evolves. 
+
+Feel free to take a look around, deploy, and make contributions. 
+
+For details about the motivation please see [this RFC](../docs/rfc/active/react-app/README.md). 
+
+## Functional Goals
+The initial milestone for the app is to achieve functional parity with the existing Ember app. This means supporting
+
+- Dataset Profiles, Search, Browse Experience
+- User Profiles, Search
+- LDAP Authentication Flow
+
+## Design Goals
+In building out a new client experience, we intend to build on learnings from the Ember app and incorporate feedback gathered
+from organizations operating DataHub. Two themes have emerged to serve as guideposts: 
+
+1. **Configurability**: The client experience should be configurable, such that deploying organizations can tailor certain 
+   aspects to their needs. This includes theme / styling configurability, showing and hiding specific functionality, 
+   customizing copy & logos, etc. 
+
+2. **Extensibility**: Extending the *functionality* of DataHub should be as simple as possible. Making changes like 
+   extending an existing entity & adding a new entity should require minimal effort and should be well covered in detailed 
+   documentation. 
+
+## Starting the Application
+
+### Quick Start
+
+Navigate to the `docker` directory and run the following to spin up the react app:
+```
+./quickstart-react.sh
+```
+at `http://localhost:9002`.
+
+If you want to make changes to the UI see them live without having to rebuild the `datahub-frontend-react` docker image, you
+can run the following in this directory:
+
+`yarn install && yarn run start`
+
+which will start a forwarding server at `localhost:3000`. Note that to fetch real data, `datahub-frontend` server will also
+need to be deployed, still at `http://localhost:9002`, to service GraphQL API requests.
+
+## Design Details
+
+### Package Organization
+
+The organization is yet subject to change as the app incubates. As of today (2/11/2021), the `src` dir of the app is
+broken down into the following modules
+
+**conf** - Stores global configuration flags that can be referenced across the app. For example, the number of 
+search results shown per page, or the placeholder text in the search bar box. It serves as a location where levels
+for functional configurability should reside. 
+
+**components** - Contains all important components of the app. It has a few sub-modules:
+
+- `auth`: Components used to render the user authentication experience. 
+- `browse`: Shared components used to render the 'browse-by-path' experience. The experience is akin to navigating a filesystem hierarchy.
+- `preview`: Shared components used to render Entity 'preview' views. These can appear in search results, browse results,
+  and within entity profile pages. 
+- `search`: Shared components used to render the full-text search experience. 
+- `shared`: Misc. shared components
+- `entity`: Contains Entity definitions, where entity-specific functionality resides.
+  Configuration is provided by implementing the 'Entity' interface. (See DatasetEntity.tsx for example) 
+  There are 2 visual components each entity should supply:
+    - `profiles`: display relevant details about an individual entity. This serves as the entity's 'profile'.
+    - `previews`: provide a 'preview', or a smaller details card, containing the most important information about an entity instance.
+
+        When rendering a preview, the entity's data and the type of preview (SEARCH, BROWSE, PREVIEW) are provided. This 
+        allows you to optionally customize the way an entities preview is rendered in different views.
+
+    - `entity registry`: There's another very important piece of code living within this module: the **EntityRegistry**. This is a layer 
+        of abstraction over the intimate details of rendering a particular entity. It is used
+        to render a view associated with a particular entity type (user, dataset, etc.).
+
+
+![entity-registry](./entity-registry.png)
+
+**graphql** - The React App talks to the `dathub-frontend` server using GraphQL. This module is where the *queries* issued
+against the server are defined. Once defined, running `yarn run generate` will code-gen TypeScript objects to make invoking 
+these queries extremely easy. An example can be found at the top of `SearchPage.tsx.`
+
+**images** - Images to be displayed within the app. This is where one would place a custom logo image. 
+
+## Adding an Entity
+
+The following outlines a series of steps required to introduce a new entity into the React app:
+
+1. Declare the GraphQL Queries required to display the new entity 
+   - If search functionality should be supported, extend the "search" query within `search.graphql` to fetch the new 
+      entity data.
+   - If browse functionality should be supported, extend the "browse" query within `browse.graphql` to fetch the new 
+      entity data. 
+   - If display a 'profile' should be supported (most often), introduce a new `<entity-name>.graphql` file that contains a 
+    `get` query to fetch the entity by primary key (urn). 
+
+    Note that your new entity *must* implement the `Entity` GraphQL type interface, and thus must have a corresponding
+     `EntityType`.
+
+
+2. Implement the `Entity` interface 
+    - Create a new folder under `src/components/entity` corresponding to your entity
+    - Create a class that implements the `Entity` interface (example: `DatasetEntity.tsx`)
+    - Provide an implementation each method defined on the interface. 
+        - This class specifies whether your new entity should be searchable & browsable, defines the names used to 
+          identify your entity when instances are rendered in collection / when entity appears 
+          in the URL path, and provides the ability to render your entity given data returned by the GQL API. 
+
+
+3. Register the new entity in the `EntityRegistry`
+    - Update `App.tsx` to register an instance of your new entity. Now your entity will be accessible via the registry 
+      and appear in the UI. To manually retrieve the info about your entity or others, simply use an instance
+      of the `EntityRegistry`, which is provided via `ReactContext` to *all* components in the hierarchy. 
+      For example
+      ```
+      entityRegistry.getCollectionName(EntityType.YOUR_NEW_ENTITY)
+      ```
+    
+That's it! For any questions, do not hesitate to reach out on the DataHub Slack community in #datahub-react.