Theo - An Open Source Neo4j Framework


Thomas Anderson is a computer programmer who maintains a double life as “Neo” the hacker. - Combination of Neo and Thomas


Theo is an open-source framework written in Swift that provides an interface for interacting with Neo4j.


The why comes from multiple reasons.

1. Swift

Over the past few months I’ve been reading and writing some small utilities and getting my feet weight with Swift. I’ve found myself really enjoying the language and wanted to do something on a larger scale. This seemed like the next logical step for me to get a better grasp on the language and it’s possibilities. It didn’t disappoint in its challenges and rewards.

2. Neo4j

Neo4j is a highly scalable, robust (fully ACID) native graph database. Neo4j is used in mission-critical apps by thousands of leading startups, enterprises, and governments around the world. -

The most common usage for graph’s is social data sets, but it should never be assumed that only social apps/services can use Neo4j. Business intelligence, content management, recommendation engines, and geo are just a few of areas of it superiority over traditional RDBMs. Customers and case studies.

My introduction to graph databases was from my good friends over at FatFractal. I saw the power and flexibility that leveraging this technology had on the variety of data that one could present. I had read a few tutorials about Neo4j, but never had the opprotunity to really dig deeper. As the need to show complex relationships in a straightforward and performant way for me grew I kept coming back to Neo4j and what it provided.

3. Challenges

Everything about the Theo was a challenge. Using a new language that has been officially 1.0 for ~month, using new Xcode features and wrapping that around Neo4j…a graph database that I’m a novice in. The rewards and excitement of using these technologies has been better than I could imagine. In all honesty I could have written the current version with Objective-C in about a quarter of the time, but I feel the greatest rewards come from the greatest challenges. Swift has a huge part in the future of iOS development and this was the perfect playground, if you will, to use it. The Neo4j API is interesting. In all honesty I don’t believe it is the most consistent API that I’ve used, but there is a ton of flexiblity in it.

  • If you look at the current version there is a lot of logic and modeling to deal with meta information. This was because in 2.1.4 the API kept a lot of it separate. However, yesterday, a maintenance release was pushed out, 2.1.5…the API now includes:

Adds additional metadata (label and ID) to node and relationship representations in JSON responses from the REST API.


I haven’t thrown out the “meta” related structs because of backwards compatibility, but please note that in future releases I will rely more on what the API returns from the nodes themselves as opposed to bridging the two.

4. I Like Working with Friends


programmer, usability hunter, potential lunch winner - love graph databases. I SAID LOVE THEM

When I worked at St. Jude Greg was my boss for 5 years. Over that time, and ever since, we’ve been good friends. For the past few years, between raising 3 kids with his wife and getting his Ph.D., he has been jetting setting (coach unfortuantely) across the country evagenlising Neo4j. As of a few months ago he started GraphStory and asked if I would like to write a Neo4j client for them. I couldn’t jump on that project fast enough.


PHP dev, motorcyclist, and amateur photographer, CTO/Lead Developer at

When I first started at St. Jude the two main languages of use where Java 1.3 and ASP (shoot me now). Needless to say the Java version need a slight bump, which it got, but the .asp had to go. Our team ended up moving over to a LAMP stack, but that also meant a ton of migration of applications and random forms to PHP. I was working on a custom CMS so we hired Jeremy as a contractor. He was solid with “function” based PHP, but had only a little experience with OO. Over the next few months I showed him a few fundamentals and settled on Zend Framework (1.0) and the next thing I knew he was extending the framework and writing the basis for our in house library that is still in use today. After he left St. Jude he went on the found the MemphisPHP user group and speaking all over the country about PHP. Say what you will about PHP, but the community is pretty awesome and Jeremy has been a big part of that. Now that he is the CTO of GraphStory…I would listen to whatever that man has to say. He has earned his place.

Ready for Production?

The code that is on Github is very stable. I’ve written tests for all the functionalty up to this point. There are still some pieces of functionality that I want to add in, as well as, make the Client object a bit more user friendly. If you are interested in contributing, find a bug or ask a question please view the README for the best way to do that. I’ll take the library as version 1.0 in the next few weeks.