tangjeff0 / precursor

Create mockups with real-time collaboration

The Pitch

Precursor 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 doc to learn about some of Precursor's features.

This is the code that runs Precursor

The Precursor founders, Danny and Daniel, have generously 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 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 for updates.

Development Requirements

Downloading jars

Some jars are hosted in a private s3 repository. You'll need the AWS secret key to download them. Unfortunately, AWS does not like it when their keys are exposed, so it has to be obfuscated here.

export

export PRCRSR_JARS_USERNAME=AKIAT7EJ2N4CR3WFDRFJ
export PRCRSR_JARS_PASSWORD=$(echo "zhLtbtGUnn7THm21k6mSNCUNg4ZxYUoqnp8NUd2h" | tr "[A-Za-z]" "[N-ZA-Mn-za-m]")

(if you don't have tr on your machine, the password is encrypted with rot13.

Frontend

Fetch our fork of Om, which is installed as a submodule (in yaks/om):

git submodule update --init

Install node dependencies (requires a recent version of node):

npm install

Compile the frontend clojurescript assets:

lein clean
lein figwheel dev

Database

Download Datomic Pro Starter Edition 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:

bin/transactor config/samples/dev-transactor-template.properties

Webserver

First, create a secrets file. Unfortunately we can't share the development secrets.

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:

gpg --armor --batch --symmetric --output my-secrets-file.edn.gpg my-secrets-file.edn

Enter your passphrase at the prompt (I've used "hello" as an example).

Start the webserver:

GPG_PASSPHRASE='hello' PROFILE_SOURCE='secrets/my-secrets-file.edn.gpg' lein run

Now you should have a server running on port 8080 and start an nrepl server on port 6005.

Go to http://localhost:8080. If you see the app, everything worked. If not, check the output of lein run for errors.

Project layout

Backend

Precursor's infrastructure is laid out in this doc https://precursor.precursorapp.com/document/Backend-Infrastructure-17592197950857

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. 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) 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. I'd recommend watching Brandon Bloom's Clojure/West talk Building CircleCI's Frontend with Om, 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. 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.

We use Figwheel to speed up development on the frontend.

Gumshoe helps us to iterate faster on the backend.

Troubleshooting

Try running:

lein clean