docs/code-overview.md

   1 # Gitter `webapp` Overview
   2
   3 ## Introduction
   4
   5 `gitter-webapp` is the main monolith for `https://gitter.im` (the Gitter web app), `https://api.gitter.im` (the Gitter API) and `https://ws.gitter.im` (The Gitter realtime socket streaming service).
   6
   7 ## Entry Points
   8
   9 There are three server processes:
  10  - [`api.js`](../api.js): serving the API
  11  - [`web.js`](../web.js): serving the web
  12  - [`websockets.js`](../websockets.js): websocket process
  13
  14 ## A Bit of History
  15
  16 This repository started as a large monolith and for the most part still is a monolith. Now we are starting to transition to a [monorepo structure](https://lerna.js.org/) and over time, more and more functionality will be moved out of the main monolith, into smaller modules.
  17
  18 These modules will initially be kept in the same repo as the monolith, but since they're fairly independent, can move out of the main repo into their own repos as team organization requirements evolve over time.
  19
  20 ## Structure
  21
  22  - [`build-scripts/`](../build-scripts): Tools and scripts related to building the application
  23  - [`config/`](../config): Configuration files
  24  - [`modules/`](../modules#modules): Monorepo style submodules
  25  - [`public/`](../public): Public assets for https://gitter.im
  26  - [`server/`](../server#server): https://gitter.im backend
  27  - [`shared/`](../shared): Isomorphic Javascript shared by frontend and backend.
  28
  29 ## Persistence
  30
  31 Gitter uses a number of backend persistence services:
  32  - **mongodb**: MongoDB is our main database technology. We use [Mongoose](http://mongoosejs.com/) as an ORM.
  33  - **redis**: We are heavy Redis users. We have four main Redis clusters. These are for:
  34     - **redis-persist**: Persistent Redis instant. If the cluster went down, ideally we should not lose any data.
  35     - **redis-nonpersist**: Non-persistent Redis. If the cluster went down and we lost all data in this cluster, it would not affect the operation of Gitter.
  36     - **redis-caching**: Similar to redis-nonpersist, but capped in size. Used for caching, particularly the **GitHub API**, which we cache using the [`request-http-cache`](https://github.com/gitterHQ/request-http-cache) module.
  37     - **redis-faye**: Used by [Faye](https://github.com/faye/faye) as a persistent backend.
  38  - **elasticsearch**
  39  - **neo4j**:
  40
  41 ## Diagrams
  42
  43 ### Overview
  44
  45 ![](./images/overview.jpg)
  46
  47 ### Software Architecture
  48
  49 ![](./images/architecture.jpg)
  50
  51 ### Dataflow
  52
  53 ![](./images/dataflow.png)
  54
  55 ### Infrastructure
  56
  57 ![](./images/infrastructure.png)
  58
  59 #### Detail of `webapp` production setup
  60
  61 The ELB balances the load between 8 webapp EC2 instances. Each webapp instance runs:
  62
  63 - 2 web express servers started from the [`server/web.js`](https://gitlab.com/gitterHQ/webapp/-/blob/develop/server/web.js)
  64 - 2 API express servers started from [`server/api.js`](https://gitlab.com/gitterHQ/webapp/-/blob/develop/server/api.js)
  65
  66 And users Nginx as a reverse proxy to route the incoming traffic based on the request path.
  67
  68 ```mermaid
  69 graph LR
  70 A((User)) -- "HTTPS (443)" --> B[ELB]
  71 B -- "HTTP (80)" --> C[Nginx]
  72 subgraph "EC2 (webapp)"
  73 C -- "/" --> D["web webapp (server/web.js)"]
  74 C -- "/api{_staging}/*" --> E["api webapp (server/api.js)"]
  75 end
  76 ```