docs(gatsby-admin): more detailed architecture explanation

packages/gatsby-admin/README.md

@@ -2,11 +2,50 @@
 
 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.
 
-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.
+### Service Discovery
 
-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.
+`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`.
+
+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:
+
+```
+$ 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
+
+`gatsby-admin` cannot be used as a plugin, as that would enable users to override anything in the `src/` folder due to theme shadowing! Instead, `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).
+
+Initially, @mxstbr published the built `gatsby-admin` files to npm and added it as a dependency to `gatsby`. However, yarn and lerna do not handle circular dependencies well. Doing this breaks `lerna bootstrap` due to `gatsby-admin` trying to build (with `gatsby`!) before `gatsby` is built.
+
+Instead, `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