Posted in September 2012

Rethinking the relationship model.

Originally I had a very simple relationship model in mind for the various building blocks of PART. But after giving it some thought, it was wrong.

One of the objectives of PART was to create a system which would consolidate all of my trades over all of my portfolios in a given book, making it easier to calculate the ACB and total aggregate return. The reason for this is that I hold some securities in different portfolios. For example, I may hold shares of one company in multiple brokerage accounts. E.g., I have a professional investment advisor at BMO Nesbitt Burns, but I also do my own trading at BMO InvestorLine. If I happen to have shares of the same company at both BMO Nesbitt Burns and BMO InvestorLine, my actual ACB is calculated as the ACB across all shares at both brokerage houses.

Further, the reason I decided on the Book model was that I could conceivably have three books: Taxable, Non-Taxable RRSP, and Non-Taxable TFSA. For the purposes of calculating capital gains, losses, and dividend income, those three books are separate: capital gains in my TSFA have no impact on capital gains in the Taxalbe account.

The error in my original model was that I had a one-to-many relationship of Book to Portfolio, and a one-to-one relationship of Portfolio to Position. This wouldn’t work with the scenario described above, since I may hold shares of some company XYZ at both BMO Nesbitt Burns and BMO InvestorLine, but the one-to-one relationship of Portfolio to Position would fail, if both the BMO Nesbitt Burns and BMO InvestorLine portfolios were taxable. In reality, there should be a one-to-one of Book to Portfolio (e.g., a book — Taxable — would have multiple portfolios (Nesbitt and InvestorLine)), but a many-to-one relationship of Portfolio to Position: a given position can be spread across multiple portfolios. This means that a trade in a given position must also know which portfolio it belongs to, but when calculating ACB for the aggregate position, it doesn’t matter which portfolio the trade occurred in, as long as they were in the same book. So if I had four portfolios in my taxable book (say, a margin account at Nesbitt, a margin account at InvestorLine, a non-margin account at Questrade, and shares I purchased via a direct share purchase program), trades across all four portfolios would contribute to the ACB and total return for the entire position.

The implications of this are:

  • Trades have to know which portfolio they belong to
  • Dividends have to know which portfolio they belong to
  • I’ll have to give extra care to the CRUD functions of trades and dividends to maintain the proper relationships

This is just food for thought, and I’m sure it will become clearer when I actually draw out the UML diagrams for the objects.

Use Me, Abuse Me.

Alright, so we have basic building blocks down.  I feel like I put the cart before the horse; I really should have sketched out these use cases before the building blocks, but c’est la vie.  Here is what, for v1, I would like the tool to do.

Use Case Description
Create Book Creates a new book.  A book requires a name and a currency.
Add trade Adds a trade to a position.  Every trade has a unique ID.
Add dividend Adds a dividend payout to a position. Every dividend has a unique ID.
List trades in position Lists all trades for a position
List trades in portfolio Lists all trades for a portfolio; this is the aggregate of all trades for all positions in the portfolio
Get YTD return for position  
Get YTD return for portfolio  
Get YTD return for book  
Get since inception return for position  
Get since inception return for portfolio  
Get since inception return for book  
Save book Saves a book and all information in the book: book metadata, portfolios, trades
Load book Loads a book and all information in the book: book metadata, portfolios, trades
Create portfolio Creates a new portfolio as part of a book.  A portfolio must have the same currency as the book that holds it.
Load equities Loads all of the known equities
Add position to portfolio Adds a position to a portfolio.  A position must be from a known entity.

For a first cut, I think this will do. I am trying to avoid from getting myself tangled up in the nitty-gritty of the CRUD for all of the use cases. For now, I’ll be using CSV (or XML?) files for a lot of the config stuff (e.g. the equities).

I’m getting a little excited about this now! With the basic use cases down, I have something to work towards. Next step will be to build out the basic command shell. I’ll be using a command pattern with the CLI to make things easier. This will also allow me to properly abstract the actual functionality from the UI. Provided my command objects all have proper output functions (i.e. toString() or similar), migrating to a UI at a later point will be much easier.


Basic building blocks

So, I sat down tonight and sketched out the basic building blocks of everything. Here is what we have.

Conceptual Architecture

    • The basic building block of PART is the book.
    • A book
      • Contains zero or more portfolios.
      • Has a name, and a currency.
    • A portfolio
      • Must have the same currency as its container book.
      • Contains one or more positions
    • A position
      • Contains exactly one equity
      • The equity must have the same currency as the portfolio, and by extension, the book
      • Contains zero or more trades
      • Contains zero or more dividends
      • May belong to more than one portfolio (and by extension, may belong to only one book, since all portfolios are in the same book)
    • An equity
      • Has a ticker
      • Has an exchange it is listed on
      • Has a currency.  The currency must be the same as the position/portfolio/book that this equity belongs to
      • Can belong to one or more portfolios
        • Note that an equity can belong to multiple portfolios; this is because the actual trades and dividends related to the equity are abstracted away in the position.
      • Can belong to only one position
    • A trade
      • Is specific to a given position-equity 2-tuple
      • Has a date
      • Has a time
      • Has a number of shares
      • Has a commission
      • Has a share price
    • A dividend
      • Is a special type of trade
      • Has only a cash portion
      • I made the executive position of only taking the aggregate dollar amount of the dividend; you could list it as the dividend per share, but that gets complicated since my statements only list it as a dollar amount and I’m lazy — I don’t want to do the math
    • A currency
      • Is a pretty basic type, it only has the currency symbol (e.g. CAD, USD, etc.)

And there we have it. That is the basis of the entire system. Of course, there are some ancillary functions such as load/save of books, add/delete/modify trades, etc. But at a high level those are the basic building blocks of everything.  I’m going to have to buy a copy of Visio or something to sketch out the appropriate UML diagram for all of these building blocks.


Welcome to the PART project.

Hello, and welcome to the PART project.

PART is an acronym for Portfolio Analysis and Reporting Tool. Snazzy, eh? It has come up out of the need for something to manage my investments. There a lot of web tools out there, but none of them do exactly what I need them to do (e.g., handling currency conversions properly), and many of them require technologies that just don’t work on my old school Quad-G5 PowerMac.

To that end, I’ve decided to dust off my old programming text books, and jump back into some simple development. It’s been a while since I’ve done any serious coding, so this will be a very interesting exercise.

Here is a high-level roadmap:

  • Decide on language, install IDE on system.
  • Articulate high level (version 1.0) requirements
  • Build basic command shell
  • Build equity functionality
  • Build portfolio functionality
  • Build book functionality
  • Build stock-feed import functionality
  • Release beta to public

I’ve decided to code this in Java, for a number of reasons:

  1. Java, IMHO, is still the most portable language. Since I develop on both a PowerPC Mac and a Windows XP computer, I need something that works on both platforms with little effort. I considered Qt as well, but it has been ages since I programmed in C/C++. Java offers a great OO language with decent memory support; the last thing I need is to be tracking memory leaks in 3AM!
  2. I have lots of old Java code that I can reuse.
  3. It’s just easier, for me anyways!

For this first iteration, I’m going to go old school and make this a console based tool: read that as, it will use a command prompt. I’ll be designing it from the ground up to use a proper MVC pattern though, so the objects will be reusable. This means that once I get the general functionality fleshed out at the command prompt, I can start teaching myself some GUI skills for Java to build a shiny interface.

Anyways, stay tuned. Lets see if I can still pull a program out of my hat.