docs(gatsby-admin): more detailed architecture explanation (#25941)

* Write more detailed Admin architecture docs * Add section on production deployment to gatsby-admin docs * Absolute URLs so they work on npm etc. * Fix pronouns and wording * Clean up some more * Tighten up language around production deployment Co-authored-by: Brent Jackson <[email protected]> * Update packages/gatsby-admin/README.md Co-authored-by: Brent Jackson <[email protected]> Co-authored-by: Brent Jackson <[email protected]>
gatsbyjs · Jul 29, 2020 · 34d0ac4 · 34d0ac4
1 parent d964d96
commit 34d0ac4
Showing 1 changed file with 40 additions and 3 deletions.
diff --git a/packages/gatsby-admin/README.md b/packages/gatsby-admin/README.md
@@ -2,11 +2,48 @@
 
 A visual interface to configure your Gatsby site.
 
-## Development
+## Architecture
+
+The Gatsby Admin interface (this package) is a standard Gatsby site.
+
+It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experimantal extension) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) for styling.
+
+It fetches its data from the [gatsby-recipes GraphQL server](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-recipes/src/graphql-server), which exposes all the information Admin needs about the locally running Gatsby site, using [urql](https://github.com/FormidableLabs/urql).
+
+It also listens to the [`gatsby develop` status server](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/commands/develop.ts), which exposes information about whether you changed the config files and need to restart the develop process.
+
+### Service Discovery
+
+`gatsby develop` automatically starts both the GraphQL and status server. However, both of these use random ports.
+
+To discover where they are (and whether they are already running) there is a service discovery mechanism in `gatsby-core-utils`. It stores the ports of the running Gatsby site(s) at `~/.config/gatsby/sites/<pathhash>/<servername>.json`.
 
-The Admin app itself is a standard Gatsby site. It fetches its data from the Recipes GraphQL server, which exposes all the information we need about the Gatsby site.
+Admin can then fetch `localhost:8000/___services` (where `:8000` is the well-known port of the running site), which returns a list of all the random ports used by the site:
 
-It uses [theme-ui](https://theme-ui.com) (with the [strict-ui](https://github.com/system-ui/theme-ui/pull/719) experiment) and [gatsby-interface](https://github.com/gatsby-inc/gatsby-interface) to style the app and [urql](https://github.com/FormidableLabs/urql) to fetch the data from the GraphQL server.
+```
+$ curl http://localhost:8000/___services | jq
+{
+  "developproxy": {
+    "port": 8000
+  },
+  "developstatusserver": {
+    "port": 60731
+  },
+  "recipesgraphqlserver": {
+    "port": 50400
+  }
+}
+```
+
+That's how the Admin frontend knows to connect to `localhost:50400/graphql` to connect to the GraphQL server, and `localhost:60731` to connect to the develop status server.
+
+### Production Deployment
+
+To avoid clashing with the local site and potential issues with shadowing, `gatsby develop` statically serves the built files from the [develop parent proxy](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby/src/utils/develop-proxy.ts).
+
+To avoid issues with yarn, lerna, and circular dependencies, `gatsby-admin` copies its built files to `gatsby/gatsby-admin-public` which is then published to npm. While not an ideal solution, it fixes the issue and works relatively reliably.
+
+## Development
 
 ### Running it locally