Two years ago Ardoq set out to build the documentation platform that the IT-professional wants to use. Starting a “greenfield” project, we were free to choose what we considered to be the best technology for the job, so we ended up using Clojure for all backend components. In this talk I will share our experience using Clojure to build the http://ardoq.com/ documentation platform. A few highlights - Building comprehensive REST-APIs in Clojure - Rapid feedback using REPL driven development - Building a “realtime web” backend using Clojure, WebSockets and Redis. I will also share some of the mistakes we made along the way, as well as lessons learned and tips for anyone starting a new Clojure project.

1. Ardoq.com @ebaxt
Erik Bakstad
Clojure
at
Ardoq
Oslo Socially Functional Programmers

2. Ardoq.com @ebaxt
! 6 years as consultant (finance/telecom)
! Mostly Java & JavaScript professionally
! Discovered Clojure in 2009
! Groovy, Ruby, Python, SML, Racket, Scala …
! CTO & Co-founder of Ardoq
My background

3. Ardoq.com @ebaxt
AGENDA
! What is Ardoq?
! Why we decided to use Clojure
! Overview Clojure at Ardoq + 2 Cases
! REPL/development environment
! Experience so far / Q&A / Discussions

4. Ardoq.com @ebaxt
What is Ardoq?

5. Ardoq.com @ebaxt
We‘re building larger, more complex systems
! Many different “sub-systems“
! Different technologies
! Wide range of integrations
! System-of-systems problem

6. Ardoq.com @ebaxt
To achieve conceptual understanding we create artifacts
! Documents
! System maps
! Diagrams
! Flowcharts
These artifacts are hard to maintain!

7. Ardoq.com @ebaxt
Existing tools are either ...
Enterprise architecture
software
Very
Complex
Word
Not
powerfull
enough
Excel
PowerPoint
Wikis
Visio

8. Ardoq.com @ebaxt
Ardoq is a documentation platform that offers
! Explorable, “Living” documentation
! Automatically visualizes dependencies and hierarchies
! REST-api for data import/export
! Supports custom visualizations via plugins

9. Ardoq.com @ebaxt
DEMO

10. Ardoq.com @ebaxt
Why Clojure?

11. Ardoq.com @ebaxt

12. Ardoq.com @ebaxt

13. Ardoq.com @ebaxt
Ship
software
Quickly
Fun!
Consistently
(over time)
Quality
Try out different
solutions
Understand
How it works!
Leverage

14. Ardoq.com @ebaxt
JavaScript
MongoDB
Clojure
BSON
JSON
{
"firstname": "Erik",
"lastname": "Bakstad",
"age": 30,
"hobby": ["hockey", "cycling"]
}
{
"firstname": "Erik",
"lastname": "Bakstad",
"age": 30,
"hobby": ["hockey", "cycling"]
}
{
:firstname "Erik"
:lastname "Bakstad"
:age 30
:hobby ["hockey", "cycling"]
}
EDN

15. Ardoq.com @ebaxt
! Extensive REST-api
! “Version control” on top of MongoDB
! Real-time web backend
! 3-party integrations (recurly, jira, segment.io, +++)
! Attachment service with pluggable storage provider
Stuff we‘ve built in Clojure

16. Ardoq.com @ebaxt
Architecture

17. Ardoq.com @ebaxt
Backbone.js !
D3.js!
jQuery!
Require.js! JavaScript-app!
Clojure!
backend!
MongoDB!
!
Redis!
HT TP Websockets SNS!
S3!
Segment.io!
Mailchimp!
Mandrill!
Recurly!
JIRA!
Tarsnap!
!
HT TP
TCP
Plugins!
JavaDoc / Excel!
HT TP

18. Ardoq.com @ebaxt
api!
com.ardoq.*
utils! service!
gateway!persistence!
MongoDB!
!
SNS!
S3!
Segment.io!
Mailchimp!
Mandrill!
Recurly!
JIRA!
!
!
hAp://www.infoq.com/presentaGons/DDDIClojure$

19. Ardoq.com @ebaxt
Libraries
! Carmine
! amazonica
! core.async
! Pantomime
! clj-http/chime/clostach
! Ring/compojure/Liberator
! http-kit/clj-wamp
! Friend/oauthentic/clj-oauth
! clj-schema/antisamy
! Monger/ragtime

20. Ardoq.com @ebaxt
Testing/debugging
! Started out with midje
! Now using clojure.test
! ring.mock
! Lein test selectors
! Mongodb + redis
! clojure.tools.trace
! IntelliJ with Cursive
! Embedded REPL
! criterium

21. Ardoq.com @ebaxt
Editor/IDE
! Emacs + Cider
! clojure-mode + paredit
! clojure-test-mode
! clojure-refactor (just started)
! company-cider

22. Ardoq.com @ebaxt
Infrastructure/monitoring
! S3 (wagon)
! SNS
! Zapier
! Tarsnap
! HipChat
! AWS / on-site
! Ansible /python/bash
! Circle-CI
! Logstash + Kibana
! Pingdom

23. Ardoq.com @ebaxt
Case 1
REST-api

24. Ardoq.com @ebaxt
Request Response
Servlet Container
Servlet AP I
Ring
Application

25. Ardoq.com @ebaxt
{:scheme(:http,(
(:session({}(
(:request3method(:get,(
(:query3string("q=hello"(
(:cookies({}(
(:uri("/test"(
(:headers(
({"accept3encoding"("gzip,(deflate"}(
(:body(...}$
(defn%handler([request](
...(
)$
{:status(200(
(:headers({"Content3Type"((
((((((((((("text/plain"}(
(:body("Hello(World!"}$

26. Ardoq.com @ebaxt
(defn%middleware([handler](
(
(
(
(
)$

27. Ardoq.com @ebaxt
(defn%middleware([handler](
(((fn%[req](
((...(
(((handler(req)(
((...(
))$

28. Ardoq.com @ebaxt
(defroutes(api(
(((GET("/"([](...)(
(((POST("/"([](...))(
(
(def%handler(
((((logging((session((security(app))))(
(
(
(run3jetty(handler({:port(8080}))$

29. Ardoq.com @ebaxt
(defroutes(api(
(((GET("/"([](...))(
?

30. Ardoq.com @ebaxt

31. Ardoq.com @ebaxt
Liberator
hAp://clojureIliberator.github.io/liberator/$
(defroutes(api(
(((GET("/"([](...))(
Decision graph

32. Ardoq.com @ebaxt
Decision graph
hAp://clojureIliberator.github.io/liberator/assets/img/decisionIgraph.svg$
(resource(
(((((((((:allowed3methods([:get](
(((((((((:allowed?((fn%[_]((permission/is3admin?))(
(((((((((:available3media3types(["application/json"](
(((((((((:exists?((fn%[_]({::result(...)(
(((((((((:handle3ok(::result)))$

33. Ardoq.com @ebaxt
Authentication
hAps://github.com/cemerick/friend$
! Basic Auth
! Token Auth
! Oauth (Log in with Github, Google, Live Connect)

34. Ardoq.com @ebaxt
Friend
hAps://github.com/cemerick/friend$

35. Ardoq.com @ebaxt
Friend
hAps://github.com/cemerick/friend$
{:workflows([(ajax3login)(
((((((((((((((token3workflow(:realm("Ardoq"(:credential3fn(...)(
((((((((((((((workflows/http3basic(:realm("Ardoq")(
((((((((((((((github3oauth(system)(
((((((((((((((live3connect3oauth(system)(
((((((((((((((google3oauth(system)](
(:credential3fn((partial(verify3credentials(system)(
(:login3uri("/login"(
(:unauthorized3redirect3uri("/login"(
(:default3landing3uri("/index.html"}$

36. Ardoq.com @ebaxt
Middleware
! wrap-impersonate
! wrap-organization
! wrap-session-expiry
! clojure-metrics

37. Ardoq.com @ebaxt
Case 2
Real-time web

38. Ardoq.com @ebaxt
API-1! API-2!
Nginx-1! Nginx-2!
Browser-1! Browser-2!
POST$/api/component$
{“name”:$“foo”}$
NoGfy$user$of$BrowserI1’s$
POST$

39. Ardoq.com @ebaxt
Why not use something like
Pusher.app or firebase?

40. Ardoq.com @ebaxt
The Web Application
Messaging Protocol
hAp://wamp.ws/$

41. Ardoq.com @ebaxt
API-1! API-2!
Nginx-1! Nginx-2!
Browser-1! Browser-2!
Websocket
+ Wamp
Http-kit
+ clj-wamp
Autobahn.js
+ flash-fallback
?

42. Ardoq.com @ebaxt
API-1! API-2!
Nginx-1! Nginx-2!
Browser-1! Browser-2!
Redis PubSub
+ core.async Redis!

43. Ardoq.com @ebaxt
Publish!
Event!
Redis!
Carmine!
listener!
Core.async!
mult-channel!
(loop!
…!
(wamp/send-event …)!
(recur))!
!
Browser-2!Browser-1!
Workspace-event
Organization-
event
dao!

44. Ardoq.com @ebaxt
Publish!
Event!
Redis!
Carmine!
listener!
Core.async!
mult-channel!
(loop!
…!
(wamp/send-event …)!
(recur))!
!
Analytics!
Testing!
dao!

45. Ardoq.com @ebaxt
REPL
Driven Development

46. Ardoq.com @ebaxt
http://thinkrelevance.com/blog/2013/06/04/clojure-workflow-reloaded
https://github.com/juxt/jig
https://github.com/stuartsierra/component
https://www.youtube.com/watch?v=13cmHf_kt-Q

47. Ardoq.com @ebaxt
The Clojure experience
So far

48. Ardoq.com @ebaxt

49. Ardoq.com @ebaxt
Other benefits
Tiny codebase
Fast feedback
Libraries (both Java and Clojure)
Concurrency

50. Ardoq.com @ebaxt
Challenges
Dynamic language - tradeoffs
Lack of signatures
LISP – with great power comes…

51. Ardoq.com @ebaxt
Thank you!
Questions?

52. Ardoq.com @ebaxt
THANK YOU!