Guidelines for Building a Neo App
From NeoWiki
The goal of this document is to provide a condensed set of guidelines for people who are familiar with the basics of Neo, but don't feel entirely confident on how to put their skills to use in a real-world application. It works on a macro- rather than a micro scale and tries to convey a mindset rather than specific details. If you want code-level patterns, see the HOWTOs.
Please note that this is a very early draft version that is no more than half done. Over the summer of 2008, we're going to make a real effort to shape up our documentation, including this guide. Until then, your best bet is to read through whatever is here, then check out the Design Guide.
Contents |
[edit] Mindset
Like most (all?) programmers today, you were probably born and raised in an RDBMS world. Having been fostered in a world where the bottom layer of all architectural diagrams is the "SQL sink," you most likely carry with you a number of assumptions. The challenge is to let go of those hidden assumptions as you now work with an architecture without a 35 year old legacy. This section includes a set of guidelines that we hope will make this easier.
[edit] Focus on the domain model
The first thing to keep in mind as you start a Neo project is to focus on the domain model. Step up to the white board, forget UML and E/R diagrams and just draw a conceptual model of your project's domain. For example, to the right is a conceptual model of one day in the life of our good friend Björn's. You can see from the white board that he owns a car, which he uses to drive his kids and groceries to the daycare. (No, we don't know why he supplies the daycare with groceries.)
When you have a first draft of your domain model, you'll notice how easy it is to represent it in the node space. Take a look at the node space to the right. It is in fact quite similar to the scribbles on the white board. Over the past five years, we've built a lot of applications on top of Neo and we've noticed that it's usually trivial to go from a domain model to a representation in the node space: all entities and their relationships from your white board are explicit in the node space (as either nodes, relationships or properties). We call this white board friendly.
So focus on the domain model. Go directly to a node space representation. And then build an object-oriented domain layer on top of the node space.
[edit] Assume the node space is always in memory (Neo will make it so)
With legacy architectures, there's usually a serialization stage between your domain model and its persistent state in the storage backend. In raw JDBC applications, you serialize your OO classes to strings that you send over the wire. In EJB applications, you use DTOs as data capsules to/from the entity layer. In other frameworks, there's commonly a load/store pattern where you first load an entity from the store, perform some operations on it and then store it back.
With Neo, forget all about that. You have a domain layer on top of the node space (see below for some pointers on that). Each domain entity typically wraps a node (or a relationship) and when you're implementing that class your mindset should be that you're working with an in-memory data structure. There's no need to load/store anything, and no need to inject data from the node space into DTOs. There's no state in your domain layer. Each entity simply wraps a node, to which it forwards all data handling requests (typically getters and setters). Your domain layer is an adaptation of the generic node space to a type safe, object-oriented abstraction expressed in the vocabulary of your domain.
[edit] Assume everything's automatically persistent (Neo will make it so)
This is a corollary to the previous guideline. When you implement your domain model, your focus should be on reading and writing data to the node space in a transactional context. The transactions are logically demarcated to follow business operations and state is shared through the node space. As a side effect, everything is persistent with proper ACID semantics. You don't ever have to worry about explicitly instructing Neo to store anything.
