update readme

Author: dwwoelfel

README.md

@@ -1,8 +1,28 @@
 # precursor
 
-## Usage
+## The Pitch
 
-Fetch the Om source, which is installed as a submodule (in yaks/om):
+[Precursor](https://precursorapp.com) is the best way to collaborate on early prototypes with your team. Start every project with a new Precursor doc, share the link with your team, hit the speaker in the lower right to share your audio, and start sketching out your ideas. It's better than Sketch, Skype, and Slack put together.
+
+Check the [How to](https://precursorapp.com/document/How-to-17592197661008) doc to learn about some of Precursor's features.
+
+## This is the code that runs Precursor
+
+The Precursor founders, [Danny](https://twitter.com/dannykingme) and [Daniel](https://twitter.com/danielwoelfel), have generously released made the Precursor code open to the public. Precursor is an excellent resource if you're interested in Clojure, ClojureScript, Datomic, advanced CSS, or just how to put together a modern web app.
+
+## Setting up your own instance
+
+If you're a company that wants to run Precursor on your own hardware, please contact [Daniel](mailto:[email protected]) for help getting set up. We've made some effort to allow anyone to spin up their own Precursor instance, but there are still some roadblocks to work around.
+
+## Contributing
+
+We're still working out requirements for this. There will likely be a contributor's agreement. Please follow [@precursorapp](https://twitter.com/precursorapp) for updates.
+
+## Development Requirements
+
+### Frontend
+
+Fetch our fork of Om, which is installed as a submodule (in yaks/om):
 
 ```
 git submodule update --init
@@ -14,43 +34,92 @@ Install node dependencies (requires a recent version of node):
 npm install
 ```
 
-Download datomic from here https://my.datomic.com/downloads/free
-
-unzip it and from within the directory run
+Compile the frontend clojurescript assets:
 
 ```
-bin/transactor config/samples/free-transactor-template.properties
+lein clean
+lein figwheel dev
 ```
 
-Start the server:
+### Database
+
+Download Datomic Pro Starter Edition [https://my.datomic.com/starter](https://my.datomic.com/starter). You'll have to create a new account with Datomic to get a license key.
+
+Unzip it Datomic and add your license key to `config/samples/dev-transactor-template.properties`
+
+Start Datomic from within the datomic directory:
 
 ```
-lein run
+bin/transactor config/samples/dev-transactor-template.properties
 ```
 
-That will start a server on port 8080 and start an nrepl on port 6005.
+### Webserver
 
+First, create a secrets file. Unfortunately we can't share the development secrets.
 
-Compile the frontend clojurescript assets:
+Copy `pc.profile/ProfileSchema` into a new file, `resources/secrets/my-secrets-file.edn`.
+
+Replace the values, filling in the fields with proper values. This part is not well-tested. You can try putting dummy values for most things. Please open issues on GitHub if you run into problems. PRs to simplify this process are very welcome.
+
+Then encrypt the file using gpg with a symmetrical passphrase:
 
 ```
-lein clean
-lein figwheel dev
+gpg --armor --batch --symmetric --output my-secrets-file.edn.gpg my-secrets-file.edn
 ```
 
-Then go to [http://localhost:8080](http://localhost:8080)
+Enter your passphrase at the prompt (I've used "hello" as an example).
 
-### Browser REPL
-
-nrepl in to the nrepl server and run:
+Start the webserver:
 
 ```
-(pc.utils/connect-browser-weasel)
+GPG_PASSPHRASE='hello' PROFILE_SOURCE='secrets/my-secrets-file.edn.gpg' lein run
 ```
 
-Then reload the app.
+Now you should have a server running on port 8080 and start an nrepl server on port 6005.
+
+Go to [http://localhost:8080](http://localhost:8080). If you see the app, everything worked. If not, check the output of `lein run` for errors.
+
+## Project layout
+
+### Backend
+
+`src/pc/init.clj` is the entry point that sets up all of the server's state
+
+`src/pc/views/` contains HTML generated by the backend. This is where the blog, admin pages, and the bootstrap HTML for the frontend live.
+
+`src/pc/models/` contains the very light layer for fetching, creating, and updating Precursor's data abstractions. We decided to stay as close to the Datomic representation as possible, and this has worked very well for us. In general, Precursor's philosophy is to use abstractions sparingly because [abstractions are hard](https://www.amazon.com/gp/product/B00DD6YDFG). Bad abstractions are usually much worse than too few abstractions.
+
+`src/pc/http/` contains the code that handles web requests lives here, except for the code that actually sets up the http server, which lives at `src/pc/server.clj`.
+
+`src/pc/http/sente.clj` is a poorly-named file (Precursor switched from Sente to [Talaria](https://github.com/dwwoelfel/talaria)) that handles realtime messages to the browser over websockets. Ideally, it would be split into multiple smaller files. You can see a better approach in `src/pc/http/issues.clj`.
+
+There is more, but those are the main pieces.
+
+### Frontend
+
+The frontend is very similar to [CircleCI's open-source frontend](https://github.com/circleci/frontend). I'd recommend watching Brandon Bloom's Clojure/West talk [Building CircleCI's Frontend with Om](https://www.youtube.com/watch?v=LNtQPSUi1iQ), for a quick overview.
+
+`src-cljs/frontend/core.cljs` is the entry point.
+
+`src-cljs/frontend/components/` contains all of the view code.
+
+`src-cljs/frontend/controllers/` contains all of the code that changes state.
+
+There is more, but those are the main pieces.
+
+### Notable libraries/software
+
+Database is Datomic, we've been very happy with it in conjunction with [Datascript](https://github.com/tonsky/datascript). I can't imagine building Precursor's realtime features without it. Some of the more advanced features we had planned, like forking and infinite undo would be much harder without it.
+
+HTTP server is Immutant. We have found it very stable. We switched from http-kit, which was also pretty good, but doesn't support features needed to implement back pressure.
+
+We manage http connections with [Talaria](https://github.com/dwwoelfel/talaria).
+
+We use [Figwheel](https://github.com/bhauman/lein-figwheel) to speed up development on the frontend.
+
+[Gumshoe](https://github.com/datodev/gumshoe) helps us to iterate faster on the backend.
 
-### Troubleshooting
+## Troubleshooting
 
 Try running: