Unless you live under a rock or really really really enjoy hand-writing every SQL query you make, chances are you’ve come across an ORM that maps your domain model to a data storage mechanism.  For Lunchage we’re opting to use NHibernate mostly out of familiarity, but also to try out the new “auto-mapping” functionality that eliminates the need for .hbm files or a third-party utility like Fluent NHibernate.  If you need a primer for using NHibernate check out their getting started guide or Ayende’s recommended learning material.

Given the domain we’ve created in the last post, I’ve got to wrap the base amount of information I want stored in the database we’re using that will be familiar across all objects.  The base “Entity” object will contain Id, Version, CreateDate and LastModified properties in order to place nice with our ORM. The Id, CreateDate and LastModified should be obvious, the Version is a field we will use to manage concurrency issues. My next move is to define how NHibernate maps our domain to the database.  As I briefly mentioned above, the newest version of NHibernate (3.2) integrated convention and configuration based mappings that rely on strongly-typed code instead of xml for transforms.  Unfortunately this is a relatively new feature and finding documentation on best practices can be difficult.  Most of what I’ve done can be referenced through Fabio Maulo’s 3.2 series of articles. To leverage this convention based power, I can define a class for our default mapping configurations.

Pretty simple eh?  This configuration should take care of 80% of what we need out of our ORM. You’ll notice there is one reference to an explicit map around line 39, that’s because we’re defining a ManyToMany for Restaurants to Tags but don’t really care or have the domain Tag class knowing about our restaurants.  Otherwise, we could probably map a convention for ManyToMany and be done with the whole process.

Once configuration is done, I write a test to create and export the schema which should verify that our domain matches the database and will detect whenever we’ve mapped something improperly.

Before this test can run, I have to define the configuration for NHibernate and this is vastly different (re: way simpler) to do than previous incarnations.  Again, though, there isn’t a ton of documentation at this time on getting configuration up and running.  Instead of configuration individual variables on the configuration object, we interact we an object called DatabaseIntegration on the Configuration to specify the db dialect and connection string.  The final step is to add the mapping files to the configuration and, BOOM, we’re ready to go.  You can still specify configuration parameters via Configuration.SetProperty(Key,Value) by why would you when half of the work is already done?  (Note though, we’ll likely need to make some changes once we get into a web environment).

That’s that.  We have enough to generate our database and have our system not die. Also at the bottom notice I’ve created a function to export our xml mapping files should we feel the need to confirm any mapping issues. If anyone out there knows a native way of doing this in NHibernate 3.2 please do tell.  We’ve made our UI decisions so we’ll now start scaffolding up the site’s layout and UI interaction in order to get some of the back-end work come together.

Mock-ups are an important part of any application creation. When creating a mock up you want to stay as simple as possible and get the idea across without an influence on the implementation. There a number of excellent tools available for creating complex UI mockups and some that are really simple.
To start, I as a product owner first want to jot down some ideas. Putting something into the computer feels permanent to me. I like paper so i will start with that.

Those were quick to do and got my ideas on paper and out of my head.
Now to focus on something more easily modifiable and that can be shared with the rest of the team. We use Balsamiq Mockups because it’s feature rich, easy to use and quick to get started with. As with any tool the more you use it the better and faster you get with it. Another awesome reason is Mockups To Go, which has even more mock up goodness for download. I spent about 30 mins on this homepage mock up, after a quick discussion over the hand drawn ones.

Now that we got our general plan for homepage we can get started with design and getting some pages out quickly. We will come back to Balsamiq Mockups in the future for other pages, for now we need to focus on showing progress to our product owners and getting their input. Since our product owners are everyone, feel free to post your ideas in the comments.

Release often, release quickly, and try to minimize the bugs!

Continuing with our full app creation series, Lunchage.

• Intro
• Domain Model

Part of my enthusiasm in creating the Lunchage application is the prospect of new beginnings.  Every new project requires significant amounts of thought into my favorite activity, modeling out a domain.  I believe the single most important aspect of a software engineer’s tool belt is the ability to translate real-world requirements into a set of classes that:

• Properly represents the problem that the software aims to solve
• Are capable of being modified with as little resistance as possible

So, with these lofty goals in mind, we’re going to be keeping a very strict sense of Object Oriented Design in mind when developing and writing out the classes in our main domain model.  I’ve dealt with plenty of DTO/Domain model hybrids in the past with feature envy and am looking to this project to display exactly how easy life can be when we allow our domain to properly encapsulate logic instead of merely providing an interface into our database as is the case with many other systems.

In you’re interested at all in following along with the code base, feel free to download it from github.

Instead of listing every property and field on all our our domain models, I’ll simply say that if a property is necessary for an object to exist, we make sure that it is passed into a constructor to force on instantiation.  In addition, we’re going to try and force all List types to be only mutable by the parent.  This means no public getter on lists, we’ll supply a public getter in the form of IEnumerable  so no other classes can modify the list.

Since our requirements dictate that users need to be able to log in and create an account with Lunchage we’re going to create a, wait for it, Account class.  I want to try an avoid having a needless amount of properties on the class so naturally my first instinct is to simply add first name, last name and email as the only identifiers of a user that I need.  Further down the line we’ll add avatar support but, in keeping in line with light requirements, that stuff is fluff so it’s out for now.  Email is the one property an account needs to be created, so we’ll force that dependency in the constructor and only have a getter backing a private property to allow field access.  In the future if we (read: when) want to allow changing the email we can add a setter with some null checking logic, but for the time being we’re creating a contract with a property that always needs to be there, so let’s make sure that it is.

Our Account class is also going to need a list of properties to track when they choose a place to have lunch.  I’ll then create a LunchSelection class, which is largely immutable, to store the relationship between a Restaurant selected, an Account and the time the lunch is supposed to take place.  After the lunch we’ll allow the user to submit series of reviews on the service, food quality etc….

The Restaurant class is just as simple as our Account class.  We need an Address to store it’s location for geo-targeting, a name, a list of descriptive Tag objects and a list of LunchSelection objects that were created in conjunction with the Restaurant.

You’ll notice we have a list of Reviews attached to the LunchSelection, this may seem a little silly at the moment, I’ll explain this decision after describing the Review class properly.  A Review is made up of a user’s Vote (Great, Ok, Bad), the Question they answered (How was the service?  How did the food taste? etc…) and the LunchSelection for bi-directional reference.  All properties on this class are immutable, largely because once you review something, you really can’t take it back.  The premise is that we want multiple mini-reviews for a LunchSelection that describe fully the experience they had.  Restaurants can be crappy some days because of service and excellent simply because of the atmosphere.  We want to capture the flowing nature of this information.

Voting in our Lunchage system is designed to be hyper-simple to the point of almost Yes-No question answer pairs.  We have to assume most people don’t want to spend the time on diatribes about the quality of their lunch, we need to capture their experience though in order to properly recommend other restaurants.  So we can ask brief questions like “How was the service?” with Netflix style emails to hopefully garner a response.  Vote is then only going to have a VoteValue, which is an enum for Great, Ok or Bad, comments should the user want to provide them and the LunchSelection it is tied to.

The last major class in our system (as per our initial requirements) is going to be the Tag.  A Tag is a name describing the type of food a restaurant serves.  Tags can range from Chinese or Italian to simply Spicy.  Our goal is to create a really dumb selection process that invites the user to blindly click buttons of words they like.  Next thing you know they’re eating lunch at a restaurant they love and have never eaten at and thanking us for making suggestions.

That’s the whole shebang.

From here the real work on the application begins.  We need to get rolling on our storage mechanism implementation and, from there, whatever testing framework we’re going to use to make sure this code-base doesn’t become a mess.  We may have to slightly alter our model once we choose ORM solutions, but we’ll get to that next time.

Again, if you want to check out the codebase, feel free to download it here.

Lunchage : The Beginning

When I first began using ASP.NET MVC as a web development framework, I found the Nerd Dinner application from Microsoft helped to learn the ropes.  The app though never really went far enough into an application’s development cycle to answer a lot of questions I had when starting a new project (to it’s credit though, that really wasn’t the point of the sample application at all).  Trying to find decent help on how to make design decisions can be found in the classic books (Patterns and DDD) but real-world examples are often made into smaller chunks without the big picture on display.  In light of this, we wanted to focus our energies to coming up with requirements for a brand new open source app and take anyone willing along for the ride.  Our open source application will function as a medium to present design decisions and challenges that we can publicly solve for the greater good.

Introducing :  Lunchage

We decided that since we like eating lunch so much and are indecisive, why wouldn’t we create an application that presented us with choices for lunch?  Ok, so right now you might be saying “Why are you making Urban Spoon?”, “Doesn’t Yelp do this?” or “You idiots really have nothing better to do huh?”.  To that, you’re probably right, but we have a few requirements that those apps don’t quite have.

So, over the next few weeks we’re going to be outlining the requirements, software stack, front-end necessities and design for the full Lunchage application.  I want to detail every thought and plan we have to show exactly how fast an app can be spun up using convention, agile methods and good design practices.  Through the programming process our range of blogs will cover object oriented design principles, modern front-end javascript frameworks, front end design and usage of HTML5, usability and maybe even mobile considerations.  The point being that we’re tackling a full scale operation and documenting the entire thing.

Requirements

Before we can get to coding anything, I’m taking the liberty of documenting the basic requirements for the team so we can all work off a unified idea.  Keeping with the Agile methodology, our requirements are going to change as we build and play around with our application so we try to keep any ideas we have loose so we can drop, defer or re-prioritize them at any time.  In my experience, creating a gigantic set of software requirements and sticking to every crossed t is a fast way to create an expensive, complicated and bloated piece of you know what.  Agile aims to keep not only the software cycle lean, but the requirements themselves.

The basic idea of our application is this: I want to log into the Lunchage application, select one to a few descriptors of food I want to eat and I want places in the area to show up.  That is all.  Any other details we add is just fluff.  Our software is going to be designed to perform one very specific task very well.

Now that we have our basic concept, other details we know we want are the ability to log-in using at least two major authentication providers (Facebook and Google for starters) and we want to be able to connect with other people in our application to share where we are having lunch for others to tag along.

The other implementation details (i.e. where we get restaurant data, do we want reviews?) will be discovered as the application is built and discovered.  The main point is that we don’t want to spent a significant amount of time and money on features that we don’t end up using.  Remember the 80/20 rule!

To finalize then, I want an application that:

1. Let’s me sign up with Facebook or Google
2. Let’s me pick food types like “Chinese” or “Spicy”
3. Gives me local places to have lunch.
4. Allows me to share that lunch choice with friends.