HLD High Level Design

This post is a follow-up on “Bootstrapping A New Project”


I’ve written about “User Stories”, a tool that helps with expectation setting when working with (mostly) non-technical stakeholders.

Designing Toward

  • database (schema, tables, indexes..)
  • application layout
  • deployment
  • modules
  • internal and external APIs
  • application infra (frameworks, tools etc..)

Design Tools At Your Disposal


  • System Architect - mostly interested in the software stack, deployment and the database design
  • Team Members - mostly interested in the more lower level stuff like modules and API’s
  • Other Teams - mostly interested in API’s

Feedback on design is great for everyone involved, setup meetings with relevant parties to do DR (design review)

UML and Other Vegetables

UML is complex, you don’t need to know it perfectly, start with what makes sense, and slowly pick up tutorials. Remember, its a visual tool that helps you communicate, not everyone who will look at your designs has the time (or cares for) to read throughly a book about UML and its specifics. In Einstein’s words “Make everything as simple as possible, but not simpler.”


Design does not last. Nobody is going to update the design as the system grows and evolves. Having said that, can still be used a good reference.

User Stories

This post is a follow-up on “Bootstrapping A New Project”

“User Story” is an important communication tool, it is used between you (the developer) and who ever is making the requirements (the stakeholder).
A “contract” which (unlike one written by a lawyer) is clear, understood and agreed upon.
On our side (development) user stories embody a work unit that can be further broken down and estimated.

Key value points:

  • Language - its key that user stories are written in a language everyone can understand (stakeholders, developers etc..)
  • Perspective - user stories need to be written from the perspective of the “feature user”, so they represent real world value
  • Estimation - to help you get better and more precise estimation for the project overall
  • Prioritization - what needs to be delivered soon/later

Lets imagine we just got a call from the product manager, where he is telling us about this new survey tool:

  1. It needs to collect answers from users via a link sent to our users by e-mail
  2. It needs to be summarized and sent to … once a month on the 1st
  3. Managers need to be able to see past surveys

Hmm.. OK, thats pretty clear, but suppose this can be written clearer, lats try using the following template: (not my invention;))
As a [role], I want [Requirement / Feature], So that [Justigication/ Reason]

The requirements now look like this:

  1. As an end user, I will be able to follow a link I got via e-mail, so that I can fill a survey and express my opinion
  2. As a manager, I will receive an e-mail with a digest of surveys, so that I can evaluate performance
  3. As a manager, I will be able to access old surveys, so that I can compare and evaluate performance over time

By reading the above I can clearly understand the required functionality and the motivation behind writing it, this gives me a good starting point.
Since I am the one to implement this, I will need to provide estimates, so that product can plan ahead and communicate the product road map onward.
Unfortunately, “The Devil is In The Details” as they say, so giving estimates based on points 1,2,3 is still difficult.
Points 2 & 3 are “huge” stories, also known as “epics”, we need to further break down these stories, while still using the same language and practices:

  1. As an end user, I will receive an email with a link as a result of some communication with a company, so that I can follow it and fill a survey
  2. As an end user, I get a set of questions to answer, so that my opinion is collected
  3. As a manager, I will receive an e-mail with a digest of surveys, so that I can evaluate companies performance
  4. As a manager, I will have a survey management portal, so that I can overview previous results and compare to
  5. As a manager, I can select a specific survey, so that I can extract meaningful actionable information

The functionality expected of deliverables from the points above is clear, and now I feel more comfortable estimating the time it will take me to complete each.
Along with the estimation, these can now be prioritized against each other and against other ongoing projects..


The beginning of a new project is the perfect time to introduce user stories, it will help with getting the conversation going, further clarifying the scope and requirements.
While the project scope might change, user stories are (optimally) modular, decoupled and encapsulated, this should help with managing changes and their effect on the overall project.

Bootstrapping A New Project

My take on: How to give your new project a good starting point

So, you have a new shiny project on your lap, so now what?
Today everyone is talking about “agile”, and how its better then the old “waterfall” methodology of doing things


The “Waterfall” approach is notorious in the software community, some highlights of why this is the case:

  • It assumes that the initial requirements will not change
  • There is only one version delivered to the stakeholders, at the end of the process
  • All the planning and “thinking” happen only in the beginning of the project


Everyone likes “Agile”, its the “cool” way to manage a project, it asks for less paperwork, less work upfront, built from the ground up to support changes, to name a few conceptions about it.
While I call it “Agile” here, in reality it is a world of sub cultures, some of which are: “XP” (eXtreme Programming), “scrum”, “Kanban” to name a few.
The difference between specific cultures is not always clear, we don’t necessarily have to stick to one, we can mix and match, like I am doing here, thus from this point onward I will just ignorantly call it “Agile” with out specifying the specific methodology.
The main strengths going for the Agile methodology are

  • Short upfront work phase (requirements, design ..)
  • Iterations - project is broken down to deliverables, which is translated to real value delivered very early in the project lifetime
  • Changes are welcome and expected and are introduced into following iterations (bugs found in previous deliverables, design “inadequacies”)

Doing things in small pieces is great, just ask a WEB developer, how there’s nothing quite like writing a bit of code, refreshing the page and seeing the changes reflected, especially when working on a big complex project. This gives you a feeling of progress and achievement, even though the end goal is far far away..

Some Agile approaches talk beyond writing business code and going into proactive bug searching using TDD (Test Driven Development), which turns out to be a good fit to the overall process as it secures quality of delivered pieces of logic.
BDD (Behavior Driven Development) is very similar to TDD, but instead of going after “test coverage” it takes on a higher level, business specification driven approach, where the business embodied user stories are part of the actual test suite.

My recipe for success

  • User Stories
  • Mock-ups (in the case of an app that has UI)
  • HLD (High Level -system component- Design)
  • Process Sequence diagram / Workflow diagram (possibly atop HLD)


Tools that keep me productive:

  • Google Document (User Stories)
  • Google Drawing (mockups, diagrams, HLD)
  • Lucidchart (diagrams)

In addition, I use a light weight web based project management tool as a central place to keep reference to important docs and user stories, and see my progress (and others working on the project). A great tool for the job is Trello.com - which free and super simple!


User Stories