docs: expand development proxy section (#192)

Closes #191

* Correct flag
* Apply suggestions from @rudolfs
Co-Authored-By: Rūdolfs Ošiņš <[email protected]>

* Apply suggestions from code review
Co-Authored-By: Merle Breitkreuz <[email protected]>
Co-Authored-By: Rūdolfs Ošiņš <[email protected]>

* Link downstream protocol projects
* Improve languag
* Correct position of test disclaimerj
* Add proxy commands with explanations
* Address feedback
Co-authored-by: Rūdolfs Ošiņš <[email protected]>
Co-authored-by: Merle Breitkreuz <[email protected]>

DEVELOPMENT.md

@@ -378,7 +378,6 @@ be used so changes to global styling can be applied in a central place.
 You can build and package Upstream with: `yarn dist`. The generated package
 will be in: `dist/` as `radicle-upstream-X.X.X.{dmg|AppImage|snap}`.
 
-
 ## Scripts
 
 To get a list of all available script commands, run: `yarn run`.
@@ -395,7 +394,7 @@ yarn dist             # Bundles Upstream into an installable package
 yarn generate:colors  # Update color CSS variables in public/colors.css from
                       # colors.json
 
-yern generate:schema  # Start proxy and save the latest GraphQL schema
+yarn generate:schema  # Start proxy and save the latest GraphQL schema
                       # in ./schema.gql
 
 yarn graphiql         # Open GraphiQL with explorer extension in browser
@@ -411,9 +410,14 @@ yarn lint             # Check UI code for linting errors
 
 ## Proxy
 
-All Upstream business logic tying together the radicle code collaboration and
-registry protocols is provided to the UI via GraphQL by a rust binary called
-the proxy.
+All of Upstream's business logic tying together the radicle code collaboration and
+registry protocols is provided to the UI via [GraphQL][gq] by a rust binary called
+the proxy. It uses [warp][wa] to serve a [Juniper][ju] powered API providing all necessary
+queries and mutations.
+
+For dependency management and execution of common tasks we use [Cargo][co]. To
+get up to speed with common functionality and manifest file intricacies consult
+the exhaustive [Cargo Book][cb].
 
 The proxy binary's lifecycle is managed by the main renderer of the UI in:
 `native/main.js`. When running `yarn dist` it is bundled together into an
@@ -422,7 +426,7 @@ application package by [electron-builder][eb].
 
 ### Running the proxy in stand-alone mode
 
-To start the proxy binary, run: `cd proxy && cargo run -- --source=memory`.
+To start the proxy binary, run: `cd proxy && cargo run -- --registry=emulator`.
 After that the GraphQL API is served on `http://127.0.0.1:8080/graphql`.
 
 
@@ -436,11 +440,72 @@ git submodule update --init --remote
 git submodule foreach "git fetch --all"
 ```
 
-Then run tests as usual: `cargo test`.
-
 💡 *You'll have to run the submodule commands every time there are any updates
 to the test fixture repository.*
 
+Then run tests as usual: `cargo test --all-features --all-targets`.
+
+We strive for two kinds of tests: classic unit tests contained in implementation
+files and integration tests. The integration tests are meant to assert correctness
+of the API provided by the proxy, these can be found under `proxy/tests`. To find
+out where to place and how to lay out tests, check the Rust book [test chapter][rt].
+
+### File structure
+
+The GraphQL API exposes the application's domain logic. Therefore we try to treat
+it as a thin layer exposing well-typed entities. The heavy lifting is done in the
+modules named after the protocols we consume - [radicle-link][rl] through it
+[radicle-surf][rs], for code collaboration and [radicle-registry][rr] for global
+unique entries for users, projects and organisations. By isolating concerns this
+way, we hope to enable ease-of-contribution to downstream teams. Empowering them
+to reflect changes in their public APIs easily with code contributions to Upstream.
+
+```
+proxy/src/
+├── coco.rs
+├── env.rs
+├── error.rs
+├── graphql
+│   ├── api.rs
+│   ├── error.rs
+│   ├── project.rs
+│   └── schema.rs
+├── graphql.rs
+├── lib.rs
+├── main.rs
+└── registry.rs
+```
+
+## Scripts
+
+To get a list of all available script commands, run: `yarn run`.
+Here is a list of the most commonly used ones:
+
+```sh
+yarn start                # Start Upstream in development mode
+
+yarn test                 # Run Cypress end-to-end tests
+yarn test:debug           # Show the Cypress GUI, handy for visual debugging
+
+yarn dist                 # Bundles Upstream into an installable package
+
+yarn generate:colors      # Update color CSS variables in public/colors.css from
+                          # colors.json
+
+yarn graphiql             # Open GraphiQL with explorer extension in browser
+
+yarn release              # Start a two-step process to cut a new release, for more
+                          # details have a look at ../DEVELOPMENT.md
+
+yarn prettier:check       # Check UI code formatting
+yarn prettier:write       # Auto-format UI code
+yarn lint                 # Check UI code for linting errors
+
+yarn proxy:build          # Build the proxy binary
+yarn proxy:build:release  # Build the release version of the proxy, stripped of debug symbols
+yarn proxy:start          # Start only the proxy with its default configuration
+yarn proxy:start:test     # Start the proxy in test mode, where state is isolated and lives in memory or temporary directories
+```
 
 ## CI setup
 
@@ -549,18 +614,27 @@ Release v0.0.11 successfully completed! 👏 🎉 🚀
 
 [ar]: https://buildkite.com/monadic/radicle-upstream/builds?branch=master
 [bk]: https://buildkite.com/monadic/radicle-upstream
+[cb]: https://doc.rust-lang.org/cargo/
 [cc]: https://www.conventionalcommits.org/en/v1.0.0
 [cl]: https://gist.github.com/Rich-Harris/0f910048478c2a6505d1c32185b61934
+[co]: https://github.com/rust-lang/cargo
 [cs]: https://help.github.com/en/github/authenticating-to-github/signing-commits
 [eb]: https://github.com/electron-userland/electron-builder
 [el]: https://www.electronjs.org
-[ge]: https://github.com/OneGraph/graphiql-explorer
 [gc]: https://cloud.google.com/sdk/docs/quickstart-macos
+[ge]: https://github.com/OneGraph/graphiql-explorer
 [gs]: https://github.com/OneGraph/graphiql-with-extensions
+[gq]: https://graphql.org/
 [hb]: https://github.com/github/hub
 [hu]: https://github.com/typicode/husky
+[ju]: https://github.com/graphql-rust/juniper
 [ls]: https://github.com/okonet/lint-staged
 [pr]: https://prettier.io
+[rl]: https://github.com/radicle-dev/radicle-link
+[rr]: https://github.com/radicle-dev/radicle-registry
+[rs]: https://github.com/radicle-dev/radicle-surf/
+[rt]: https://doc.rust-lang.org/book/ch11-01-writing-tests.html
 [se]: https://svelte.dev
 [sv]: https://github.com/conventional-changelog/standard-version
 [tp]: https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[wa]: https://github.com/seanmonstar/warp

package.json

@@ -88,7 +88,6 @@
     "svelte:watch": "yarn svelte:clean && rollup -c -w",
     "proxy:build": "cd proxy && cargo build --all-features --all-targets",
     "proxy:build:release": "cd proxy && cargo build --release --all-features --all-targets",
-    "proxy:build:test": "cd proxy && cargo test --no-run",
     "proxy:start": "cd proxy && cargo run --release -- --registry=emulator",
     "proxy:start:test": "cd proxy && cargo run -- --registry=emulator --test",
     "graphiql": "open http://localhost:5000",