Merge pull request #18 from dolbyio-samples/redo-readme-structure

Re-do read me structure

README.md

@@ -20,7 +20,7 @@ This project demonstrates what an events experience is like, built using React.
 |                | Chat with other participants*           |                       |
 |                | Promote a viewer to co-host*            |                       |
 
-> * Requires a PubNub account to work on these features.
+> * Requires a PubNub account to work.
 
 ## Requirements and supported platforms
 
@@ -43,18 +43,106 @@ Refer to [this guide](#how-to-get-a-dolbyio-account) on how to obtain your Dolby
 
 [![Deploy to Netlify from fork](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/dolbyio-samples/comms-app-react-events)
 
-## Running locally
+## Getting Started
 
-Please see [the events package readme](./events/README.md) for information on how to run the app locally.
+The following steps will quickly get you started testing the Dolby.io Communications APIs capabilities.
+
+### Pre-requisites
+
+To build this app, you will need a Dolby.io account (see the **How to get a Dolby.io account** section).
+
+You will also need to install the following:
+
+* [Node v18.0.0 or higher](https://nodejs.org/en/download)
+* [NPM v8.11 or higher](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+* [Yarn v1.22.19](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable)
+
+### Basic terminology
+
+As you browse through the source code and documents, you might come across some of these terms:
+
+* **A host** is a participant with additional permissions to manage the conference and other participants.
+* **A viewer** is a participant who can only receive video and audio stream from the conference.
+* A **proxy-app-server** is an intermediary API server that communicates with the Dolby.io Communications Platform in order to provide functionality such as RTS/RTMP/HLS streaming or consuming web-hook data. You can see our sample implementation [here](./backend).
 
 ### How to get a Dolby.io account
 
-To setup your Dolby.io account, go to the [Dolby.io dashboard](https://dolby.io) and register for an account. After confirming your email address, you will be logged in.
+To set up your Dolby.io account, go to [Dolby.io](https://dolby.io) and register for an account. After confirming your email address, you will be logged in.
 
 > If you did not receive a verification email, check your Spam or Junk email folders.
 
+#### Setting up your [Dolby.io](https://dashboard.dolby.io) app
+
+To set up your app for events, you will need to:
+
+1. Go to the _Dashboard_, and click `add new app` if you do not have an existing app. ![dashboard](events/documentation//dashboard-events.png)
+2. To enable events streaming, your app should be opted into the open beta program. You can find this at the bottom of the `Communications APIs` sidebar navigation when you click on your app.
+
+ ![dashboard](events/documentation/open-beta.png)
+
+## How to run the Events app
+
+To run the application locally, clone the repository and then perform the following steps.
+
+### Install dependencies
+
+**note** : This guide is written with [Yarn](https://yarnpkg.com/) in mind. We have not validated this project with other package managers.
+
+Open a terminal window in the root directory of your project folder. Install the project's dependencies using the following command.
+
+```bash
+yarn
+```
+
+### Repo structure
+
+The code in this repository is organised in the following way
+
+* The `/events/src/` directory contains all the front-end code for the events app. Within this directory:
+  * `hooks/` contains wrapper functions around our SDK for re-usable functionality.
+  * `components/` contains UI components that encapsulate and provide functionality.
+  * `utils/` provides some generic helper functions.
+  * `context/` contains the React Context for the side drawer and the main component window.
+
+* The `/backend/` contains the code for the proxy server.
+
+This project is built with the [Comms UI Kit for React](https://github.com/dolbyio/comms-uikit-react) library for simplicity and re-use of standard Communications API-based components.
+
+### Set up `.env` file
+
+Create a new file called `.env` in the `events` folder and copy the contents of `.env.example` into it.
+
+You will need to provide the values for `KEY` and `SECRET` from your Dolby.io app. To obtain your key and secret from the Dolby.io dashboard:
+
+1. Go to the _Dashboard_ and click on the `API Keys` next to your application.
+   ![dashboard](events/documentation/dashboard.png)
+2. On the next screen, copy the `App key` and `App secret` and paste them in your `.env` file against the marked variables.
+   ![token](events/documentation/client_access_token.png)
+
+To enable chat and the ability to promote a viewer to host, you will need to provide your `PUBNUB_PUBLISH_KEY`, `PUBNUB_SUBSCRIBE_KEY`, and `PUBNUB_SECRET_KEY` as well. To setup PubNub, please go through the [enabling chat guide in our customization guide](customization.md/#enabling-chat-and-promoting-a-viewer-to-co-host).
+
+The secrets will not be exposed on the frontend.
+
+#### Running the app
+
+To run the application locally, execute the command below inside the `/events` directory.
+
+```bash
+yarn dev
+```
+
+#### Open the app in a browser
+
+Once the dev server starts, open <http://localhost:3000> in the browser. The application will launch at this address and will look like the screenshot below.
+
+![built](events/documentation/home.png)
+
+## Making the App your own
+
+Follow our [customization guide](./customization.md) to better understand how you can extend the app to make it your own.
+
 ## More resources
 
 Want to experience the app without building it? Try our Virtual Events [Demo app](https://events.experience.dolby.io).
 
-Looking for more sample apps and projects? Head to the [Dolby.io Project Gallery](https://docs.dolby.io/communications-apis/page/gallery).
+Looking for more sample apps and projects? Head to the [Dolby.io Project Gallery](https://dolby.io/project-gallery/).

events/customization.md → customization.md

@@ -2,7 +2,7 @@
 
 ## Changing the labels in the app
 
-To change the labels in the app, you can modify [en.json](src/translations/en.json) and change the labels as necessary.
+To change the labels in the app, you can modify [en.json](events/src/translations/en.json) and change the labels as necessary.
 To add a new string, add a new key-value pair to the JSON file. You can then reference that new key in the code as follows:
 
 ```javascript
@@ -38,9 +38,7 @@ To add a company logo in place of our placeholder `logo` in the events app, you
 // You will need to wrap your `img` in a div tag to make sure it fits in fine and doesn't bloat the size of the TopBar.
 ```
 
-## Enabling chat
-
-### Chat
+## Enabling chat and promoting a viewer to co-host
 
 The chat and "promoting a viewer to a co-host" features in this sample app are powered by [PubNub](https://www.pubnub.com). PubNub allows us to asynchronously send messages across all instances of an event with low latency and thus offering a compelling experience. You can get started with PubNub by following [this guide](https://www.pubnub.com/docs/general/basics/set-up-your-account).