The first design of “WordChain”…

In my post named “Project born from pain…” I’ve talked about a simple project I want to create. Why? Because I’ve injured my back and just lying in bed or sitting around isn’t me. I need to do something useful while my back is healing again. My regular work is a bit out of the question since I can’t focus much at this moment. Pain makes it difficult to concentrate. However, ideas still fill my head and a simple design can be created with something simple like pen and paper. So I started my design just like that!

People tend to confuse things like software programming and software design. When you’re designing software, you will have to start with drawing all kinds of schematics depicting what you want, what you need and what it should look like. And these days people just start opening their favorite UML modelling tool or just start their development software and they start designing. But this early in a project it’s just easier to draw things with pen and paper and just forget the limitation that software would imply upon your design. You need to visualize what you want before trying to make it fit within a proper design model. People often forget this.

And how about programming? Programming is about just three things: steps, decisions and jumps. Nothing more, nothing less. Steps are the actions you take, like assigning a value to a variable. Decisions are conditional statements like “if” and “switch” that make you choose which direction you will continue to step. And jumps are to skip parts of code, most often used combined with a condition to either skip a few steps or to repeat a few steps. Once you master these things, you’re a programmer. Then again, you will need the skills to translate designs into these three things…

So, I’m still taking the first steps, which means I’m a designer now, not a programmer. I needed to create a working title for this project and “WordChain” sounds just right. Why? Because the purpose of this project is to chain definitions of words together. You start with one word, which is defined on the screen and which links to related words. Those related words link to more words and the result is a large collection of related words describing whatever I want to describe.

And it’s practical use? Well, it could be used as a manual for some product. You start with the product and the linked words will bring you to related topics. Or you use it to create a simple encyclopedia. Or maybe even a diary, where each word related to a new thing you’ve done. The options are plenty and it would be nice if WordChain would be available from its own website, explaining itself.

So let’s start with the drawing I just made. Just with pen and paper, in multiple colors. I’ve scanned it as a “Portable Network Graphic” file and reduced the colors to 256 colors to cut the file size.

WordChain screenYeah, I could have opened Visual Studio, create a simple HTML file to make the same drawing and posted that instead. But creating this with pen and paper took less than ten minutes and did not need me to consider any limitations of HTML or whatever else. I want something that looks like this, and this early in the project I just don’t want any restrictions, since that stifles creativity.

The screen has three large sections. A header containing parts A, B, C and D. A footer containing part K. And a body that’s divided into three subsections. The left subsection contains parts E and F. The right subsection contains parts I and J. The center subsection contains parts G and H. And technically speaking, part D and it’s three sub-parts should be seen as part of the body, but they just stick within the header part.

So, what are these parts?

A is a simple icon that’s either the default icon for the whole site or it’s overridden by the specific topic.

B is the selected word. This would also appear in the URL of the web browser.

C shows a few aliases for this specific word that all share the same definition. We shouldn’t display too many aliases though.

D are tabs for predefined words that we always want to show. Think, for example, about a “Help”, “About” or “Home” tab. These should be visible as tabs and should just link to these specific words in the system.

E is a word cloud, displaying related words in different sizes which the visitor can select. I’m not sure which condition should decide the word size, but the amount of words shown should be limited.

F is a list of hyperlinks that open a new browser window when clicked. In this new window, some external website would be shown. For example, F might contain the word “Blog” and clicking on it would open my weblog. Blog might also appear in E but if I click there, I would just see the definition of this word, and perhaps a few links to other blogs will appear under F.

G is the description of the word, as HTML formatted text. There should not be many restrictions to this, although I prefer to limit the HTML options to simple formatting options, just like WordPress is doing.

H is an image that’s related to the word. Although the HTML format would allow me to include images within the description of G, a separate area for a topic-related image would be nice here. I would probably need to change the positions of G and H, though. Because H would imply it’s an image topic, not a word topic. The image would be more important, thus it should be on top. The description would then be optional, and below the image.

I is a list of phrases leading to other topics, just like the word cloud in E would do. The difference between E and I is that E would be single words, while I has complete phrases like “Who is Wim?” or “What does Wim do?” for a topic about the word “Wim”. (Which happens to be my name.) Phrases would be used to offer more information about a single word.

J has a list of images related to the specific word, and they would open within a new browser window. These images will be internal images that are linked to the specific word. The URL of these images would start with the word, followed by a slash and the name of the image. Images can be shared between words, but these links between words and images need to be created in the setup before they appear here.

K is the footer and can be anything in HTML format. The footer will never change and most likely contain some copyright information, useful links and whatever else you want to display on every page. For example, in Europe there’s some dumb cookie law and you could use this footer to display a warning that your site might use cookies.

With these parts now designed, it’s time to consider the whole project model. And again, pen and paper are very practical…

WordChain modelThis model is quite simple, actually. I have two database models. One is for the user account management, since the setup application is most likely going to need me to log in before I can make any changes. The other is for the WordChain data itself and it’s something I will define in my next step.

While user management is also important, it’s more a background task which can be delayed until later. Creating and filling the WordChain database will allow me to set up the site very quickly without any need for users. This delay in design allows me to consider all kinds of solutions.

Since I have two databases, I also need two models within my .NET code. Since I’m using Visual Studio, these will be Entity Framework models. And yes, for now I will consider using the Entity Framework to manage the user accounts, but this is still something I might redesign in the future. It’s just there so I won’t forget about it.

Next, I have a web server that connects to the WordChain model. This just uses the read-only methods that are provided by the model, although there might be some write-actions if I want to keep track of the most popular words. (E.g. by maintaining a counter for every word that is requested.)

The web server will be accessed from a web browser and thus every visitor can start moving around the big list of words that I will create in the database.

On the other side I have a web service which connects to both the WordChain database and the User Account database. Here we will manage the log in options and allow users to change the content of the WordChain database based upon their access rights. This is a web service and not a web site, thus allowing me to write all kinds of applications to connect to this all. This would allow me to e.g. create an Android application that allows me to manage the whole system, instead of the need to do everything within HTML. It provides more flexibility to manage the data. Still, if I want I can still build a web site that invokes this service.

The web service would need me to generate a client library to invoke this service. This library would need to handle the log in and all data retrieval and manipulations. I probably need to create multiple libraries for multiple development environments but for now I’ll just keep it simple. And “simple” means that I will just create a .NET assembly and import the web service reference as starting point, thus allowing me to consider my exact needs.

The client library will by itself be used again by some client application. My goal is to mix multiple technologies so I’m considering to build this client in Delphi or in Oxygene. But this is still far, far away since the design of the web server is more important. For now, I could just simply manage the test data using SQL scripts…

So, where to go now? Well, I need the WordChain database and model, so I would need to open Visual Studio and design this all model-first. The Entity Framework will in its turn generate the SQL script I need to create the database. I can then create several test applications that will generate some data to test my model, fill it with stuff and do some basic manipulations. These will be my test cases.

Once this is done, I can design the web site itself, which would be a simple MVC application with a simple layout and two routing options. One routing option which just has a word, which results in a page. And one which has a word and an image name, which results in just an image.

But first the data model, which again will need me to start making notes, with pen and paper. I need to look at the first image, decide which data I need and how things will need to relate to one another. Once done, that model can be translated to an Entity Framework model.

Project born from pain…

It was February 14, 2013. I had the flu, but needed medicines for my Diabetes. So I had no choice, took my car to drive the 800 meters (!) from home to the apothecary to pick them up. It was snowing a bit, the streets were slippery because and well.. My car just made sure that I did not have to walk over 800 meters of slippery, icy streets. Just about 20 meters.

It did not work. I slipped and badly injured my back while I tried to get back into the car after picking up my medicines. I managed to stand up reasonably quickly, which assured me that I had not broken anything severe, but the pain… The pain…

I’ve started this project on Sunday, four days later. The pain is still there and my physician subscribed Paracetamol 1.000 mg and Ibuprofen 600 mg, three times per day. That’s probably enough to sedate a horse, but I still feel the pain. To make it worse, it just hurts most when I try to stand or sit, although standing or sitting quietly will bring the pain down again. So here I am, sitting at my computer, trying to deal with the pain and making my mind wonder about what to do. Still, as times passes by, I do manage to handle the pain better.

Well, that’s not too difficult. I’m just going to create a new project which I would consider practical and educational. I don’t know how much time it will take to finish but that’s no big deal since I’m not going anywhere. But first, what should the project be?

Well, after considering how Wikipedia and Twitter work, I think it would be nice to have something with similar, practical usage. A website that links words and phrases together by hyperlinks and short texts. This could even be expanded by adding images, video and other content, as long as things are kept short. I am thinking about a header with an icon and title, a few special tabs on the right side for specific topics and beneath the title the working area. Below the working area there would be a footer with copyright information and other stuff about the site itself.

The working area would be divided into three parts. A left column containing a word cloud showing the mostly related words to the current topic, with a list of links below for outside references to other websites. The right column would contain short phrases which would also lead to other topics, plus a list of related meta-data like images, videos, documents and other stuff. The center part would be the main content and would contain a short description, possibly with a small image or video included. This content area might also contain an input-form so visitors can offer their own data here.

This would be a perfect web site to create using Visual Studio 2012 with MVC 4. Plus the entity framework for storage. However, there is another challenge: how to fill it with data? And for this, I decided on a reasonable unique concept: a second website! Why? Because I want the main website to be read-only. A root domain name followed by the word that needs to be looked up, nothing more. I have no use for a “/setup” or “/admin” path because that would mean I could not use the words “setup” or “admin” as descriptions. A second site that would share the same database would be more practical.

But two sites means using two (sub)domains. But that’s not a big problem. All I need to do first is add those two sub domains to my current domain. So I go to my domain registrar and add two A labels to my DNS settings. I want to create word.wimtenbrink.nl for the site itself and wordsetup.wimtenbrink.nl for the configuration site. And I need to tell IIS on my web server to start hosting those sites, even if they’re not doing anything. It will take some time for the DNS system to actually find my sites but by reserving the domain names already, I have one delay less once I really need to start testing in a production environment.

Then again, this production environment is still experimental. If the project is finally finished, the real version will be hosted somewhere else. Most likely under Microsoft Azure or a RackSpace cloud. Why? Because my simple web server at home won’t be able to handle more than a few requests per minute.

Now I have the whole hosting solution ready so it’s time to design a few things. I start with the user interface of the site itself. This should tell me the data that I will need to store. And this can simply be drawn with pen and paper. Once the design is done, I need to consider the data that I see within my design and how to store it all. Storage would end up in an SQL Server database plus a small bit within the configuration file of the project. Once storage is done, I need to think of a web service that will allow me access to this data, and I would need to do that one twice. Once for read-only access for the site itself and once with read/write options for the setup. (And the reading part would be shared between both.) Once the web service is set up, I can start designing the user interfaces. The site itself will use MVC 4 and ASP.NET with C# as the programming language. The setup is something that I want to be a challenge so I’m considering to write it as a client/server desktop application and possibly port it to Android using Delphi or Oxygene.

All in all, this project will thus have the following steps, which I will elaborate in some next posts:

  1. Design the user interface on paper. Scan it, add some descriptions to it and make a functional design.
  2. Consider all data that needs to be stored, create a database structure by generating an Entity Framework model around the data.
  3. Define the web service methods that I need and find a simple way to share all read methods between two different websites.
  4. Create the user interface for the web site. Use a simple SQL script to fill it with some dummy data.
  5. Build the setup application using whatever technique is most appropriate.

And yes, this is a waterfall technique. If I was more than one person, Scrum could be very useful since multiple me’s could work on each separate thing. Since I want to create it all by myself, doing it step by step will be good enough.

And now back to bed. It took three days to write this all with all the pain in my back. At least in bed I can easily hold the pen and paper and do the first step…

The CART system.

In a earlier post I’ve discussed the Items-Transactions-Contracts principle. Today, I am going to expand my views on this topic with the CART system, which is basically a system that can handle items, transactions and contracts.

CART stands for Catalog, Actions, Rules and Templates. And yes, you might already see how ITC fits into CART. The catalog contains all items in your system. The actions are the transactions of your system. The rules are your contracts. And the templates are all the templates you’ve defined for the items, transactions and contracts.

For those who want to look for a matching database model in this system: don’t! There is no model that can handle it all. These are actually four different class models and classes are more than simple database models. They include code that act upon the data. But if you do want to create a data model, just consider this as a system with four different models that are connected to one another. (Maybe three if the templates are only defined by code and metadata.)

When you create a new system, you first have to set up the catalog. Why? Because the catalog is the inventory of everything that you’re going to handle. Next, you set up the actions so you know what you can do with those items. In general, you can just move them around, create new ones or remove existing items. This is all arranged by the actions system. Once you have defined all actions, you start to combine them into rules. If you want to sell an item to a customer, you’re probably end up with several connected transaction. One that sends the item to the customer, one that receives the payment from the customer and maybe one related to VAT that you have to send to the Tax Office. Thus a single sale actually results in several actions. Once you have defined all catalogs, actions and rules, you’ve probably created the templates too. Because every definition of an item, transaction or contract will end up in your template system.

So, let’s consider a simple example to use this principle upon. Let’s organize a garage sale. Say, you have a goal to reach: $500. You want to reach this by selling all your old stuff thus you announce a garage sale. You create a few flyers and you make some cold lemonade so you have some added expenses that you also have to earn back. And to keep track of it all, you want a system to keep track of all the numbers.

First of all, you already have a basic CART system with simple templates for contracts, transactions and items. An item is just a GUID to identify the item. You won’t need anything more. The transaction is a record with a GUID as identification and three other GUID’s for the sender, receiver and the item itself. Sender and receiver can be null. Last, you will need a contract which will also have a GUID as identifier and a link to the transaction templates that it supports. Which also means that you need a way to store templates in some way, but let’s identify them with a single GUID too, plus a unique name and version number. (The version number is required if you’re going to support it and want to alter the system in the future.)

First of all, you define the persons. One is you, the salesperson. One is the customer. Templates for these are simple and more than the basic item plus a name would not be required. You would also create similar item types for the goal you want to reach and the expenses you have. The goal type could have an extra description to explain the goal in more details. Then you will create the type for the items that you’re going to sell. Call them products and give them a name and a short description. Add a monetary field to the record for the default price. You might give discounts but this would be the price you would ask. And maybe even a picture if this is going to be an online garage sale. Since you’re going to give away lemonade and perhaps snacks too, you might also want to create an item type for these, since these will result in added expenses. These too would have a name and a cost price. This all will be your catalog and all these definitions are stored in your templates system. (Which could have any form. A Database model, class definitions, whatever.)

Next, you will fill them with records. Add yourself as salesperson. If your wife and kids are also helping, add them too as sales persons. However, adding more than one salesperson might need an additional shop item, with transactions between shop ans salesperson to move products. Add a single customer record, unless you have a few customers who are special or when you want to keep track of your customers. In that latter case, you would have to add customer records when you sell an item to a new customer.

Add all the things you want to sell to the products. When you’re selling lemonade, make sure you also add “Glass of lemonade” as product! Finally, add the expenses that you’re likely are going to have. Bags of chips or peanuts, bottles of lemonades or whatever else you use to make lemonade, glasses, if you use real glasses to serve your customers because even if they return the glasses, some might break. Or paper cups if you don’t use glasses. Anything that you think is important to keep track of.

Next, the actions with all possible transactions. And suddenly you will realize that I haven’t added “money” as item. Yeah, that’s right. I forgot, so add a new type to the items for money. Simply the ID and the name “Money”. Then add a money record for the currency of your choice. Add multiple records if you want to support multiple currencies, although that would make trading a bit more difficult, since it means that you will have to convert the base prices of the items to the different currencies.

So, let’s define a few transactions. First of all you can have one where the salesperson sends a product to the customer. The customer would then have to send money back to you. The product transaction is simple: salesperson, product, customer. The money transaction is a bit more complex, since it has a customer, money and salesperson field, but also an amount field to specify the exact amount that is paid.

If you want to allow refunds, you would also need transactions for the reverse order. These would be different transaction types. (Then again, you could also delete existing transaction records but then you’ll lose a historic overview.

Next, you will need money transactions to send money from the salesperson to the goal and to send money from the salesperson to the expenses. But expenses and goal have a limit to the amounts they can receive so whatever remains would be profit. Which reminds me, I’ve forgotten to add “Profit” as an item type. Add it, with one profit record.

Did you notice that I did not add an amount field to the goal and the expenses? That’s because we’re going to set these values by transactions! To set up our goal, we need a transaction with the goal as sender, since we want to reduce its amount. When the goal reaches zero, its solved. (Same for expenses.) And it’s a money transaction so the item we’re sending would be money and we need an additional amount field. The target is void, null. We could define an extra item that we’re using to specify the exact destinations that the money is used for, but for our sales system, it’s just not important enough. Remember: we don’t have to include the whole world in our application!

The expenses are a bit similar, although here the sender is a specific expense. And the amount would default to the amount specified by the expense itself. (Unless we got a discount when we buy a new bottle of lemonade, of course.) And again, these amounts are sent to the void, unless you want to keep track of where you’ve bought the stuff.

So now we have transactions for customers making purchases, customers asking for refunds and for maintaining the expenses and keeping track of reaching our goal. And already we see the rules in this all! One rule is for making purchases. A customer buys something so we have two transactions. A product moves to the customer and money to the salesperson. However, we need more transactions, since the money is used to reach our goal! So the purchase rule would need a transaction to send money to the expenses first, because we first need to pay the expenses before we have money available for our goal. Once the expenses reaches zero, we can add money to our goal. When our goal reaches zero, we add money to our profit.

When we allow refunds, we’ll need a refund rule, which would basically do the reverse of a purchase. But refunds will need us to move money away from our profit, goal or even expenses. So when we do a refund, we first lower our profit, making sure we never get a profit below zero. When we have no profits, we will add the refund as an extra expense. Don’t subtract it from our goal but just remember that we can only reach our goal when our goal and our expenses have reached zero. So, basically if we have to do a lot of refunds, we have a lot of expenses, even though we have reached out goal.

And we need a rule for our expenses, which basically means we’re going to the supermarket to buy snacks and lemonade to serve. Since we don’t really care about the supermarket, we’ll just receive lemonade and snacks from the void while sending money to the void. (Actually, we could have replaced our customers by the void too, but it’s better to use customers so we know which transactions are actually sales and refunds, and which ones are just expenses.

So now we have a bunch of contract and transaction templates:

Purchase contract:

  • Salesperson gives the product to customer.
  • Customer gives money to salesperson.
  • Salesperson adds money to expenses.
  • Salesperson adds money to goal.
  • Salesperson adds money to profit.

Refund contract:

  • Customer gives the product to salesperson.
  • Salesperson gives money to customer.
  • Salesperson removes money from profit.
  • Salesperson removes money from expenses.

Expense contract:

  • Salesperson removes expense item. 

Shopping contract:

  • Salesperson removes money from expenses.
  • Salesperson adds Expense items.

Balance contract:

  • Profit moves money to expenses.
  • Profit moves money to goal.
  • Goal moves money to expenses.

Setup contract:

  • Remove money from goal.
  • Remove money from expenses.
  • Add salesperson.
  • Add shop if multiple sales persons are added.
  • Add customer.
  • Add products to salesperson. (Or shop.)
  • Add expense items.

When you use multiple sales persons, you might consider adding transactions to send products from the shop to the salesperson, and back again for the refunds. You can also choose to have products sent directly from the shop to the customer, with the money being paid to the salesperson. You might want to keep track of how much each salesperson makes, otherwise it’s no use to have multiple sales persons. Your salesperson would be the shop. The products transactions between shop and sales persons would be to keep track of who sold which item…

This all defines our CART system for a simple garage sale. We have a bunch of items in our catalog, a bunch of possible actions and six contracts. All of them defined as templates and the contracts will need some code to check for the actual status of our goal, our expenses and even keeping track of our expense items, because when we run out of lemonade, we might need to buy more.

The next step would be to design some data models for the four different systems, to connect them and to finally create a nice user interface for the application. But that’s a nice challenge for my readers. Just keep in mind that you’re supposed to keep things simple.

Before you start selling, you would need to set up the shop, which would need the setup contract to be used.

And at the end of the sale, what you would like to do is to check if your expenses are zero. If they’re below zero, you will need to balance the three accounts. (Expenses, goal and profit.) This requires the balance contract that I’ve added to the list. Basically, your expenses must reach zero, else the whole thing has been a huge loss. Next, your goal needs to be zero, else you haven’t reached your goal. Finally, whatever is in your profit will be your profit of the garage sale, which you might use to celebrate a great action.

Next, if you want to build the thing in some client-server style, the contracts would be the web methods that you will need to create. You will also need a method to give you all the items in your system, which you will need in your client. Your client might want to display each and every purchase and refund so you might want to get all these contracts with related transactions. But you’re probably more interested in the current status so it’s more likely that you just want to see the amounts left in your goal, expenses and profits, and perhaps also for each salesperson. Basically, that would just be a method that would sum up all money transactions related to a specific item. You would send the item ID to the server and it would return an amount back.

Visual Studio 2012

Today, around dinner, the mailman arrived with a special package for me. An expensive one, but one that also makes me very happy. It was a big box containing a second box. The second box contained about 8 CD/DVD’s with Microsoft Visual Studio 2012 professional on it. And two with Windows 8, one for 32-bits systems and one for 64-bits systems. Also a DVD with SQL Server 2012 and one with Team Foundation Server 2012 on it. One with Windows 2008 Server and finally one with .NET 4.5 SDK/DDK on it.

Too bad it isn’t weekend yet, because I definitely want to start using it all!

Anyways, I’m now installing Windows 8 on an Asus EEE PC with touchscreen and Windows 7. That promises to become very interesting! I already had a netbook with Windows 8 RT with touchscreen but RT isn’t Windows 8 Professional. I hope the upgrade goes well, since I’m considering to upgrade my desktop system too, if I like Windows 8 well enough. I don’t like the Metro-look, though. But that’s something I’ll have to get used to.

Visual Studio 2012 will allow me to develop Metro-applications. That’s very interesting, but only if Windows 8 will have a reasonable large market-segment. Right now, it’s less popular than Linux on the desktop so that’s a bad start. But things will change. Windows 8 will grow sooner or later. I do wonder if it will be powerful enough to be used as a tablet-system, since the competition with Android and Apple is very tough. The Microsoft App market isn’t very large at this moment either so it’s difficult to get some nice applications for my netbook. My laptop will be able to use older Windows applications so I don’t have a problem there, but the tablet-version is limited in the applications it can support. That’s because it’s build on a different processor than the regular Windows versions.

Included in the box is also a subscriber ID for my MSDN account. That’s important since I can download a lot more free applications and development tools from the Microsoft site. Older Windows versions, older SQL Server versions, even MS Office 95 and Embedded C++ 4.0! Or Visual Basic 6.0 and 2003. Or Visual FoxPro 7, 8 or 9. Or a few Windows XP, XP Embedded, Vista and Windows 7 licences. But I’m more interested in Windows Server 2012, since I also have a web server at home. Do I date to upgrade it? Better try it first in a virtual machine!

Anyway, I’m busy this weekend!

Software development…

Today, I want to talk about designing software. Basically, I want to explore my principle of items-transactions-contracts (ITC) that I’ve discussed before. But let’s look back on those first.

An item is just that. It’s something that you have to work with. It can be a person, or it can be a currency. Maybe it’s a product or just a description of a product. Whatever it is, it’s something that has data that you need to use. Items can be containers for other items, thus items have children and one parent. Like a box of matches that has two matches. Or a person who is part of a household.

Transactions will handle amounts and describe movements of items. Basically, a transaction is nothing more than a message saying that an x amount of item A is moved from item B to item C. A could be a bike that is moved from the shop to its new owner. Or it’s a crate that’s moved from shore to a boat. Or it’s an amount in Euro’s that’s deposited in your bank account from your employer. Transactions allow you to move around data, but also to create or remove items from your system by moving them from to towards the void. (The null container, meaning either recipient or sender is null.) Transactions are also related to time, since a transaction will happen at a specific moment.

Contracts are used to group transactions together. Most transactions are part of a collection of transactions that are related to one another for a special purpose. For example, your savings account will give interest but to get that interest, you first need to put money in your account, and wait for a while. You do a transaction and your bank will follow-up with transactions. Another example is when you send a package overseas. First you deliver the package to the post office, which will give you a receipt back, confirming your delivery. The post office will then move the package around by truck to the harbor, then by boat to cross the sea to the next harbor where a truck will pick it up again to bring it to the post office nearest to the delivery address. And then a mailman will deliver the package. And in every step the post office will send transactions back to keep track of the package so it won’t get lost.

Each of these are governed by templates. You can have templates describing specific types of items or specific types of transactions. You would generally also use templates for contracts. Most object-oriented developers are already familiar with templates and refer to them as “classes” or “object types”. But if you create dynamic objects, you would have to deal with dynamic templates to describe the layout of the data.

When you look at your design, you should try to see if you can divide your data in these four groups: Items, Transactions, Contracts and templates. You will notice that many systems won’t match this pattern. You will also notice that projects that don’t match this pattern might have some limitations on what you can change about them without doing a lot of re-factoring. So, does this pattern work for real-world solutions? Well, let’s set up a design.

The case: a movie theater wants a completely new system to do its administration. So the first step would be to find the items that you would need. Of course, you’d be dealing with persons, with movies, with merchandise and snacks and soft-drinks and of course with tickets. But you would also have to work with chairs, since people want to sit while watching the movie. And the theater hall where you will play the movie. Maybe you also want to keep track of the equipment. But that latter thing isn’t very important. One more thing that is important is money. Money is a strange item but you still need to keep track of your money…

Well, the persons can be divided into multiple groups. You have employees who you need to pay and who collect tips from visitors. They might also receive commission from the sales of snacks and drinks. You will need a lot of data about your employees.

You would also have visitors, but in general a simple headcount would be enough. You could have special visitors like movie directors or actors who visit your theater so your system might want to keep track of some special visitors. (It would also allow visitors to subscribe to your theater.)

And then the contacts that you’re in business with. You need to buy the movie rights, buy the food and drinks from distributors, maintain the address of your accountant and other important persons and maybe even keep a list of important actors and directors whose movies you want to show. This would be a generic address book, but you might want to link these to specific items in your system through transactions. If you use Microsoft Outlook, these would be in your Outlook Contacts, but your system could link to it and e.g. send an order when your stock runs out of soda.

So, we have a list of item templates already, and it’s already growing fast. The next step would be determining the transaction and contract templates and link them to the item templates. For example, your employees work for you so you have contracts with them. For every specific amount of time they give you, you will give them a specific amount of money. This is their salary. Also, the commission means that for every amount of products that they sell, they will receive a small percentage of the profits on those items. So if they sell a soda for 2 Euro’s, they might receive 4 Euro-cents in commission.

Next the visitors, who also have a contract with you. They buy a ticket which will give them access to a specific hall at a specific time for a specific duration. In the most complex situation, you have a transaction for the payment, one for giving the ticket and one for the visitor to move from the void to a specific chair in your hall. And another move of the visitor from the chair back to the void when the movie is over.

And then you have the transactions with your distributors and suppliers. You need to buy movie rights and maybe you have a specific contract with your distributor which provides you with 12 movies per year for a fixed price. So one money transaction from you to the distributor and 12 transactions from the distributor to you. Your suppliers will also have plenty of transactions. You pay them for a crate full soda drinks, which they deliver. But they will also pay you back for the empty packaging, which would be the crate and the empty bottles.

To put this all in a design, you would at least need three tables. One for items, one for transactions and one for contracts. You would also need a place to keep the templates, but those could be just part of your code. There’s no need to make things more complex if you don’t need the extra flexibility.

The tables should not be simple database tables. You need a more object-oriented database system. In Visual Studio you have such an option by using the entity framework. This framework will allow you to add inheritance to your tables so the Persons table would inherit from the Items table. Thus, a person would still be an item, but an item isn’t a person. By using inheritance you could set up a simple, generic system for all the things I’ve described above and once you’re done, you have a great engine for your administration project. You can easily expand it with more functionality and depending on how you’ve set it up the migration to newer versions would be very simple. The entity framework will give you a powerful data layer and your next step would be to build a business layer and GUI for this project.

When you follow the ITC principle, then any developer should have no problems recognizing the purpose of any data item in the project. You might replace your complete development team with a new team, and the new team would easily see the layout of your datamodel. No complex documentation would be required since the hierarchy of your data tables would give more than enough information already. Just be aware that no one should step away from this principle or else your project becomes more complex again…

A generic data model.

A lot of developers will work on software that is doing some administrative tasks. And each and every developer will have to come up with a data model (or object model) which would contain everything they need. And most of the time, they will choose a model that solves their own specific situation but which is hard to change if something new is required. And that’s because developers are too busy looking for details and thus they won’t see the general image.

The general image is that you basically deal with just four kinds of data. No matter if you’re building a web-shop, in-house banking solution, patient record administration or complex financial applications, you always have just four kinds of data: items, relations, transactions and contracts. So let’s take a closer look at these data entities…

Items

Items are just what the name suggests. It’s something physical in general, although electronic data and other things could also be considered items. Persons are items. A complete household is an item. Companies are items, so are products. Animals are items. Phones are items. And most importantly, money is an item. Items are the things you’re going to administer.

Items can be unique. For example, a person is unique. But when you just keep track of the number of employees without looking at the individual, then you basically have an infinite amount. The same with money since each coin is unique, but your bank account can technically hold quite a lot of those coins. Or none at all. Basically, you could subdivide items into two parts: singular and plural items. But this is just a special property for the Item entity. You could add a field called “IsPlural” to the entity or create two child classes that you derive from the Item object. (SingularItem and PluralItem.)

Relations

Relationships are what connects two items with one another. And there can be quite a lot of relations. A person has a father and mother and most have four grandparents, although some might not be alive anymore. Many people also have children. Other relationships could be a bank account that’s owned by a person, a certain amount of money in this bank account and you could also think of the relationships between an employee and his employer.

Relationships can be very complex but keep in mind that there are just two sides on any relationship. examples: I have 10 dollars. Mary-Anne works for McDonalds. This envelope contains a letter. By keeping it simple, the data model stays simple, although you might need multiple relationships to describe certain situation, like employment, your bank account or perhaps even your mortgage.

Contract

This is where you will need a contract, although that might sound a bit of strange when talking about family relations. Basically, it’s just something that will connect items to other items through relations. And, often enough, the word matches the collection of relations just fine. For example, when you work for an employer you will deal with several different relations. First of all, the direct relation between employer and employee. But also the relations between employee and salary, plus employer to salary. But also you and your colleagues will be related, although that would be implied because the generic relation between employees and employer. And of course there’s a relation between you and the office where you work, you and the desk that you work on, or the computer that you use at work. There are plenty of relations that you can define but in general, stick to just those relations that matter.

Contracts not only maintain relationships but in general will contain some logic to change those relations or that are related to specific actions that need to be taken to maintain the relationship.

Transactions

However, there’s one more thing we have to be aware of. And that’s time. And time changes things. People might have a divorce, lose their job or easier: spend money. In the employment example, there are many transactions to think of. Salary happens to be a regular transaction where the employee receives an amount of money. The employer will have to spend this, and the tax office will also have a small claim on the amount the employer pays out. Again, just focus on the transactions that are considered important within your solution.

In general, there are two kinds of transactions. One that creates a relationship and one that breaks it. But a transaction also occurs on a certain moment in time, be it the past or the future. And often the connection between items will require multiple transaction to describe a complete situation. We have the employer who loses a certain amount to pay salaries. We have the tax office (and other offices) that will receive money related to the salary. And the employee will receive an amount related to the salary. And these relations are linked to a contract. The same contract that defined the relations between the items.

Transactions don’t have to involve money, although they often do. But if you buy a steak at the local butcher, you not only have two transactions for you losing money and the butcher earning money (who will lose some again for VAT) but there’s also the transaction of the butcher losing a steak and you gaining a steak.

Conclusion

When you’re doing the financial administration for a company, you will deal automatically with items, contracts, relations and transaction, even though you might not realize it. When you’re building software for a library to keep track of book loans, you also have a similar setup, where transactions determine who is lending which book and when it’s expected to be returned.

Even when you’re baking a cake, you could apply this data model. All ingredients and utensils would be items. The recipe would be the contract. The relations are basically simple since the item is either an ingredient of the final cake, it it is used to bake the cake. And the transactions are just describing how you should put the ingredients into a bowl, mix them, fill the pan, put the pan in the oven, remove it from the oven, remove the cake from the pan, add ingredients to give cake some color and additional taste and then use a knife to slice the cake and eat it. Each of those steps should be taken at a specific moment in time and the transactions will specify when it’s time.

It is a strange example but it shows how flexible the data model actually is. So look at your own projects and see if you can recognize these entities that I’ve just described. Most software will have entities with multiple functions, where e.g. a Person record contains a link to parent records or child records. Or links to employer, bank accounts or whatever else. In general, such constructions would severely limit your options. And although a person won’t have more than two parents in general, a person could have two or more employers. So sad if your system can only handle one employer…

And while you don’t have to use this data model for your own solution, altering your data model to match this one will improve the flexibility of your whole design.